diff --git a/docs/c-runtime-library/ansi-c-compliance.md b/docs/c-runtime-library/ansi-c-compliance.md index a097cad3fe7..115280fb685 100644 --- a/docs/c-runtime-library/ansi-c-compliance.md +++ b/docs/c-runtime-library/ansi-c-compliance.md @@ -13,7 +13,7 @@ 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 such 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 diff --git a/docs/c-runtime-library/argument-access.md b/docs/c-runtime-library/argument-access.md index 2a6a3a1e19a..a19f0ec69ac 100644 --- a/docs/c-runtime-library/argument-access.md +++ b/docs/c-runtime-library/argument-access.md @@ -8,7 +8,7 @@ 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 diff --git a/docs/c-runtime-library/buffer-manipulation.md b/docs/c-runtime-library/buffer-manipulation.md index 61d3589c832..bcf5dfc49a8 100644 --- a/docs/c-runtime-library/buffer-manipulation.md +++ b/docs/c-runtime-library/buffer-manipulation.md @@ -22,7 +22,7 @@ Use these routines to work with areas of memory on a byte-by-byte basis. |[`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 diff --git a/docs/c-runtime-library/cgets-cgetws.md b/docs/c-runtime-library/cgets-cgetws.md index c33970deb4a..4513784af30 100644 --- a/docs/c-runtime-library/cgets-cgetws.md +++ b/docs/c-runtime-library/cgets-cgetws.md @@ -46,7 +46,7 @@ Storage location for data. ## 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](./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 @@ -60,7 +60,7 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| |`_cgetts`|`_cgets`|`_cgets`|`_cgetws`| diff --git a/docs/c-runtime-library/character-classification.md b/docs/c-runtime-library/character-classification.md index 8a681f4c413..8a8cad773d2 100644 --- a/docs/c-runtime-library/character-classification.md +++ b/docs/c-runtime-library/character-classification.md @@ -10,7 +10,7 @@ ms.assetid: 3b6c8f0b-9701-407a-b384-9086698773f5 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. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +The 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)`: @@ -47,7 +47,7 @@ if ((c >= 'A') && (c <= 'Z')) || ((c >= 'a') && (c <= 'z')) |[`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| +|[`_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 diff --git a/docs/c-runtime-library/code-pages.md b/docs/c-runtime-library/code-pages.md index 6105f2e6807..e61fe0e5ee8 100644 --- a/docs/c-runtime-library/code-pages.md +++ b/docs/c-runtime-library/code-pages.md @@ -26,7 +26,7 @@ The Microsoft runtime library uses the following types of code pages: - 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 diff --git a/docs/c-runtime-library/crtdbg-map-alloc.md b/docs/c-runtime-library/crtdbg-map-alloc.md index e3abf793449..b37fb5729e6 100644 --- a/docs/c-runtime-library/crtdbg-map-alloc.md +++ b/docs/c-runtime-library/crtdbg-map-alloc.md @@ -8,7 +8,7 @@ ms.assetid: 435242b8-caea-4063-b765-4a608200312b --- # `_CRTDBG_MAP_ALLOC` -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. +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). diff --git a/docs/c-runtime-library/crtdbgflag.md b/docs/c-runtime-library/crtdbgflag.md index 5881b3e0b56..c9902015d66 100644 --- a/docs/c-runtime-library/crtdbgflag.md +++ b/docs/c-runtime-library/crtdbgflag.md @@ -8,7 +8,7 @@ ms.assetid: 9e7adb47-8ab9-4e19-81d5-e2f237979973 --- # `_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`](./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. +The **`_crtDbgFlag`** flag consists of five bit-fields that control how memory allocations on the debug version of the heap are tracked, verified, reported, and dumped. The bit fields of the flag are set using the [`_CrtSetDbgFlag`](./reference/crtsetdbgflag.md) function. This flag and its bit fields are declared in Crtdbg.h. This flag is only available when the [`_DEBUG`](./debug.md) flag has been defined in the application. For more information about using this flag along with other debug functions, see [Heap state reporting functions](/visualstudio/debugger/crt-debug-heap-details). diff --git a/docs/c-runtime-library/data-type-constants.md b/docs/c-runtime-library/data-type-constants.md index 4e7b75dfb6a..7d12148e366 100644 --- a/docs/c-runtime-library/data-type-constants.md +++ b/docs/c-runtime-library/data-type-constants.md @@ -22,42 +22,42 @@ These constants give the ranges for the integral data types. To use these consta |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| +|`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 @@ -69,45 +69,45 @@ The following constants give the range and other characteristics of the **`long |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| +|`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 diff --git a/docs/c-runtime-library/debug-routines.md b/docs/c-runtime-library/debug-routines.md index 612b6cf6e84..a6b32a239df 100644 --- a/docs/c-runtime-library/debug-routines.md +++ b/docs/c-runtime-library/debug-routines.md @@ -24,8 +24,8 @@ To use these routines, the [`_DEBUG`](./debug.md) flag must be defined. All of t | Routine | Use | |--|--| -| [`_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 | +| [`_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 | @@ -122,7 +122,7 @@ The debugger can be used to step through the source code for most of the C runti :::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 isn't 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 diff --git a/docs/c-runtime-library/direction-flag.md b/docs/c-runtime-library/direction-flag.md index 3eabde54165..1acd9cfb5f3 100644 --- a/docs/c-runtime-library/direction-flag.md +++ b/docs/c-runtime-library/direction-flag.md @@ -8,7 +8,7 @@ ms.assetid: 0836b4af-dbbb-4ab8-a4b2-156f2e2099e2 --- # 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'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. diff --git a/docs/c-runtime-library/directory-control.md b/docs/c-runtime-library/directory-control.md index 2a9a09f2824..51cf82210a0 100644 --- a/docs/c-runtime-library/directory-control.md +++ b/docs/c-runtime-library/directory-control.md @@ -17,7 +17,7 @@ These routines access, modify, and obtain information about the directory struct |[`_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.| +|[`_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| diff --git a/docs/c-runtime-library/dllonexit.md b/docs/c-runtime-library/dllonexit.md index ba66ea8efb2..6c65b6dc478 100644 --- a/docs/c-runtime-library/dllonexit.md +++ b/docs/c-runtime-library/dllonexit.md @@ -36,7 +36,7 @@ Pointer to variable that points to the end of a list of functions to execute on ## 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 diff --git a/docs/c-runtime-library/environ-wenviron.md b/docs/c-runtime-library/environ-wenviron.md index 851582e8081..5b0042df3da 100644 --- a/docs/c-runtime-library/environ-wenviron.md +++ b/docs/c-runtime-library/environ-wenviron.md @@ -35,9 +35,9 @@ 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. diff --git a/docs/c-runtime-library/errno-constants.md b/docs/c-runtime-library/errno-constants.md index a2a079d4302..57db146f7bd 100644 --- a/docs/c-runtime-library/errno-constants.md +++ b/docs/c-runtime-library/errno-constants.md @@ -15,13 +15,13 @@ helpviewer_keywords: ["E2BIG constant", "EACCES constant", "EAGAIN constant", "E ## Remarks -The **`errno`** constants are values assigned to [`errno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) for 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`](./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 | |--|--|--| diff --git a/docs/c-runtime-library/error-handling-crt.md b/docs/c-runtime-library/error-handling-crt.md index 0165ae6a88a..2be864988b1 100644 --- a/docs/c-runtime-library/error-handling-crt.md +++ b/docs/c-runtime-library/error-handling-crt.md @@ -14,13 +14,13 @@ Use these routines to handle program errors. |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.| +|[`_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.| +|[`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.| +|[`_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 diff --git a/docs/c-runtime-library/exception-handling-routines.md b/docs/c-runtime-library/exception-handling-routines.md index 9318d030d97..2d099a16f0b 100644 --- a/docs/c-runtime-library/exception-handling-routines.md +++ b/docs/c-runtime-library/exception-handling-routines.md @@ -15,10 +15,10 @@ Use the C++ exception-handling functions to recover from unexpected events durin |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| +|[`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 diff --git a/docs/c-runtime-library/exec-wexec-functions.md b/docs/c-runtime-library/exec-wexec-functions.md index a5d1f69c4bc..e0be1f4f149 100644 --- a/docs/c-runtime-library/exec-wexec-functions.md +++ b/docs/c-runtime-library/exec-wexec-functions.md @@ -71,9 +71,9 @@ The argument pointers can be passed as separate parameters (in `_execl`, `_execl 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. (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. +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`. diff --git a/docs/c-runtime-library/floating-point-support.md b/docs/c-runtime-library/floating-point-support.md index e8f6976ac25..2eac29ba5cb 100644 --- a/docs/c-runtime-library/floating-point-support.md +++ b/docs/c-runtime-library/floating-point-support.md @@ -110,7 +110,7 @@ Previous 16-bit versions of Microsoft C/C++ and Microsoft Visual C++ supported t [`_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`** +[`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 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 5dd38b8a478..54c1770dc63 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 @@ -11,7 +11,7 @@ The various `printf` and `wprintf` functions take a format string and optional a 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 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. diff --git a/docs/c-runtime-library/freeentry-usedentry.md b/docs/c-runtime-library/freeentry-usedentry.md index f24ce19ff69..7559a0c75f1 100644 --- a/docs/c-runtime-library/freeentry-usedentry.md +++ b/docs/c-runtime-library/freeentry-usedentry.md @@ -16,7 +16,7 @@ ms.assetid: 26f658e6-6846-4a4e-9984-262cfe392770 ## 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 diff --git a/docs/c-runtime-library/getmainargs-wgetmainargs.md b/docs/c-runtime-library/getmainargs-wgetmainargs.md index 3d3602667a6..c271c58c4ef 100644 --- a/docs/c-runtime-library/getmainargs-wgetmainargs.md +++ b/docs/c-runtime-library/getmainargs-wgetmainargs.md @@ -38,10 +38,10 @@ int __wgetmainargs ( 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]`. +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. +An array of strings that represent the variables set in the user's environment. This array is terminated by a `NULL` entry. *`doWildCard`*\ An integer that if set to 1 expands the wildcards in the command line arguments, or if set to 0 does nothing. diff --git a/docs/c-runtime-library/gets-getws.md b/docs/c-runtime-library/gets-getws.md index 9c0c7f467e5..a561ff2a59e 100644 --- a/docs/c-runtime-library/gets-getws.md +++ b/docs/c-runtime-library/gets-getws.md @@ -45,7 +45,7 @@ Storage location for input string. ## Return value -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`. +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 @@ -60,7 +60,7 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |`_getts`|`gets`|`gets`|`_getws`| diff --git a/docs/c-runtime-library/heap-constants.md b/docs/c-runtime-library/heap-constants.md index 5f8bf7164f1..25d20136c76 100644 --- a/docs/c-runtime-library/heap-constants.md +++ b/docs/c-runtime-library/heap-constants.md @@ -22,10 +22,10 @@ These constants give the return value indicating status of the heap. |--------------|-------------| |`_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).| +|`_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).| +|`_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 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 24d5dcd23d9..e5d8c9d54db 100644 --- a/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md +++ b/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md @@ -8,7 +8,7 @@ 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`](./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 diff --git a/docs/c-runtime-library/ismbc-routines.md b/docs/c-runtime-library/ismbc-routines.md index 8858e5d209b..1b479219fe2 100644 --- a/docs/c-runtime-library/ismbc-routines.md +++ b/docs/c-runtime-library/ismbc-routines.md @@ -11,7 +11,7 @@ ms.assetid: b8995391-7857-4ac3-9a1e-de946eb4464d --- # `_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=""::: @@ -26,9 +26,9 @@ Each **_ismbc** routine tests a given multibyte character `c` for a particular c ## Remarks -The test result of each **_ismbc** routine depends on the multibyte code page in effect. Multibyte code pages have single-byte alphabetic characters. By default, the multibyte code page is set to the system-default ANSI code page obtained from the operating system at program startup. You can query or change the multibyte code page in use with [`_getmbcp`](./reference/getmbcp.md) or [`_setmbcp`](./reference/setmbcp.md), respectively. +The test result of each `_ismbc` routine depends on the multibyte code page in effect. Multibyte code pages have single-byte alphabetic characters. By default, the multibyte code page is set to the system-default ANSI code page obtained from the operating system at program startup. You can query or change the multibyte code page in use with [`_getmbcp`](./reference/getmbcp.md) or [`_setmbcp`](./reference/setmbcp.md), respectively. -The output value is affected by the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +The output value is affected by the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. |Routine|Test condition|Code page 932 example| |-------------|--------------------|---------------------------| diff --git a/docs/c-runtime-library/locale.md b/docs/c-runtime-library/locale.md index 4dc63fe87ec..bdb8539ff77 100644 --- a/docs/c-runtime-library/locale.md +++ b/docs/c-runtime-library/locale.md @@ -19,43 +19,43 @@ More secure versions of the functions in the following table are available, indi |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`**| +|[`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)| +|[`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`**| +|[`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](./reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md)|Compare characters of two strings|`LC_COLLATE`| +|[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](./reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)|Compare two strings without regard to case|`LC_CTYPE`| +|[`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](./reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md)|Compare characters of two strings (case insensitive)|`LC_COLLATE`| +|[`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](./reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|Compare first **`n`** characters of two strings|`LC_COLLATE`| +|[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](./reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)|Compare characters of two strings without regard to case.|`LC_CTYPE`| +|[`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](./reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|Compare first **`n`** characters of two strings (case insensitive)|`LC_COLLATE`| +|[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](./reference/strftime-wcsftime-strftime-l-wcsftime-l.md)|Format date and time value according to supplied **`format`** argument|`LC_TIME`| +|[`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](./reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md),[`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](./reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)|Convert, in place, each uppercase letter in given string to lowercase|`LC_CTYPE`| +|[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](./reference/strtod-strtod-l-wcstod-wcstod-l.md)|Convert character string to **`double`** value|`LC_NUMERIC` (determines radix character recognition)| +|[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](./reference/strtol-wcstol-strtol-l-wcstol-l.md)|Convert character string to **`long`** value|`LC_NUMERIC` (determines radix character recognition)| +|[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](./reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md)|Convert character string to unsigned long value|`LC_NUMERIC` (determines radix character recognition)| +|[`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](./reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md),[`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](./reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)|Convert, in place, each lowercase letter in string to uppercase|`LC_CTYPE`| +|[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)|Transform string into collated form according to locale|`LC_COLLATE`| +|[`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md),[`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](./reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Convert given character to corresponding lowercase character|`LC_CTYPE`| +|[`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md),[`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](./reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Convert given character to corresponding uppercase letter|`LC_CTYPE`| +|[`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md),[`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters|`LC_CTYPE`| +|[`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md),[`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character|`LC_CTYPE`| > [!NOTE] -> For multibyte routines, the multibyte code page must be equivalent to the locale set with [`setlocale`](./reference/setlocale-wsetlocale.md). [`_setmbcp`](./reference/setmbcp.md), with an argument of **`_MB_CP_LOCALE`** makes the multibyte code page the same as the **`setlocale`** code page. +> For multibyte routines, the multibyte code page must be equivalent to the locale set with [`setlocale`](./reference/setlocale-wsetlocale.md). [`_setmbcp`](./reference/setmbcp.md), with an argument of `_MB_CP_LOCALE` makes the multibyte code page the same as the **`setlocale`** code page. ## See also diff --git a/docs/c-runtime-library/low-level-i-o.md b/docs/c-runtime-library/low-level-i-o.md index f89cf6df174..27470ca9d2c 100644 --- a/docs/c-runtime-library/low-level-i-o.md +++ b/docs/c-runtime-library/low-level-i-o.md @@ -16,7 +16,7 @@ Low-level routines can access the standard streams opened at program startup usi |**`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 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 diff --git a/docs/c-runtime-library/null-crt.md b/docs/c-runtime-library/null-crt.md index 38b2316f534..99eb4bc5e52 100644 --- a/docs/c-runtime-library/null-crt.md +++ b/docs/c-runtime-library/null-crt.md @@ -8,7 +8,7 @@ ms.assetid: f9aac2a0-4f79-423f-8738-a76dccc0b1c3 --- # `NULL` (CRT) -**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. +`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 diff --git a/docs/c-runtime-library/parameter-validation.md b/docs/c-runtime-library/parameter-validation.md index 647f64917c9..a2d188ec7ed 100644 --- a/docs/c-runtime-library/parameter-validation.md +++ b/docs/c-runtime-library/parameter-validation.md @@ -8,7 +8,7 @@ ms.assetid: 019dd5f0-dc61-4d2e-b4e9-b66409ddf1f2 --- # 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 diff --git a/docs/c-runtime-library/pgmptr-wpgmptr.md b/docs/c-runtime-library/pgmptr-wpgmptr.md index 03a2bd5edcd..3ce4220da5c 100644 --- a/docs/c-runtime-library/pgmptr-wpgmptr.md +++ b/docs/c-runtime-library/pgmptr-wpgmptr.md @@ -31,7 +31,7 @@ When a program isn't run from the command line, `_pgmptr` might be initialized t ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| |`_tpgmptr`|`_pgmptr`|`_pgmptr`|`_wpgmptr`| diff --git a/docs/c-runtime-library/process-and-environment-control.md b/docs/c-runtime-library/process-and-environment-control.md index 4aba4ea1164..782d02c87b4 100644 --- a/docs/c-runtime-library/process-and-environment-control.md +++ b/docs/c-runtime-library/process-and-environment-control.md @@ -24,12 +24,12 @@ Use the process-control routines to start, stop, and manage processes from withi |[`_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| +|[`_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| +|[`_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| @@ -46,17 +46,17 @@ Use the process-control routines to start, stop, and manage processes from withi |[`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| +|[`_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| +|[`_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`** 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. diff --git a/docs/c-runtime-library/reference/abort.md b/docs/c-runtime-library/reference/abort.md index 1e1c911d425..f14439b1bb5 100644 --- a/docs/c-runtime-library/reference/abort.md +++ b/docs/c-runtime-library/reference/abort.md @@ -38,7 +38,7 @@ In previous versions of the C runtime library, this message was displayed: > This application has requested the Runtime to terminate it in an unusual way. Please contact the application's support team for more information. -When the program is compiled in debug mode, the message box displays options to **Abort**, **Retry**, or **Ignore**. If the user chooses **Abort**, the program terminates immediately and returns an exit code of 3. If the user chooses **Retry**, a debugger is invoked for just-in-time debugging, if available. If the user chooses **Ignore**, **abort** continues normal processing. +When the program is compiled in debug mode, the message box displays options to **Abort**, **Retry**, or **Ignore**. If the user chooses **Abort**, the program terminates immediately and returns an exit code of 3. If the user chooses **Retry**, a debugger is invoked for just-in-time debugging, if available. If the user chooses **Ignore**, **`abort`** continues normal processing. In both retail and debug builds, **`abort`** then checks whether an abort signal handler is set. If a non-default signal handler is set, **`abort`** calls `raise(SIGABRT)`. Use the [`signal`](signal.md) function to associate an abort signal handler function with the `SIGABRT` signal. You can perform custom actions—for example, clean up resources or log information—and terminate the app with your own error code in the handler function. If no custom signal handler is defined, **`abort`** doesn't raise the `SIGABRT` signal. @@ -46,7 +46,7 @@ By default, in non-debug builds of desktop or console apps, **`abort`** then inv 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-compliant behavior. Compliant behavior may come at some cost in Windows compatibility. +For Windows compatibility reasons, when **`abort`** calls `_exit`, it may invoke the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API, which in turn allows DLL termination routines to run. Destructors aren't run in the executable, but the same may not be true of DLLs loaded in the executable's process space. This behavior doesn't strictly conform to the C++ standard. To immediately terminate a process including any DLLs, use the Windows [`TerminateProcess`](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminateprocess) API. You can also register an abort signal handler that invokes `TerminateProcess` for standard-compliant behavior. Compliant behavior may come at some cost in Windows compatibility. For more information about CRT debugging, see [CRT debugging techniques](/visualstudio/debugger/crt-debugging-techniques). 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 4976ad244f3..586f48371c0 100644 --- a/docs/c-runtime-library/reference/access-s-waccess-s.md +++ b/docs/c-runtime-library/reference/access-s-waccess-s.md @@ -49,7 +49,7 @@ For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr` ## 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| |----------------|---------------------| @@ -58,30 +58,30 @@ When used with files, the **_access_s** function determines whether the specifie |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 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. -**_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`* 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`. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|`_taccess_s`|**_access_s**|**_access_s**|**_waccess_s**| +|`_taccess_s`|**`_access_s`**|**`_access_s`**|**`_waccess_s`**| ## Requirements |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_access_s**|\|\| -|**_waccess_s**|\ or \|\| +|**`_access_s`**|\|\| +|**`_waccess_s`**|\ or \|\| ## Example -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 diff --git a/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md b/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md index 477d85477af..2dd55a042e6 100644 --- a/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md +++ b/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md @@ -33,7 +33,7 @@ Floating-point value. ## Return value -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. +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| |-----------|-------------------|--------------------------| @@ -42,7 +42,7 @@ The **acosh** functions return the inverse hyperbolic cosine (arc hyperbolic cos ## 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](../tgmath.md) for details. @@ -52,7 +52,7 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**acosh**, **acoshf**, **acoshl**|\|\| +|**`acosh`**, **`acoshf`**, **`acoshl`**|\|\| |**acosh()** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-free-dbg.md b/docs/c-runtime-library/reference/aligned-free-dbg.md index 0f7910ee260..9ebb81e2e2a 100644 --- a/docs/c-runtime-library/reference/aligned-free-dbg.md +++ b/docs/c-runtime-library/reference/aligned-free-dbg.md @@ -29,9 +29,9 @@ A pointer to the memory block that was returned to the [`_aligned_malloc`](align ## Remarks -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. +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 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. +**`_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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -41,7 +41,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_free_dbg**|\| +|**`_aligned_free_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-free.md b/docs/c-runtime-library/reference/aligned-free.md index 43f0058a5a4..4416fbbce86 100644 --- a/docs/c-runtime-library/reference/aligned-free.md +++ b/docs/c-runtime-library/reference/aligned-free.md @@ -29,9 +29,9 @@ A pointer to the memory block that was returned to the `_aligned_malloc` or `_al ## 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 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). +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 behavior, see [Global state in the CRT](../global-state.md). @@ -39,7 +39,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_free**|\| +|**`_aligned_free`**|\| ## Example diff --git a/docs/c-runtime-library/reference/aligned-malloc-dbg.md b/docs/c-runtime-library/reference/aligned-malloc-dbg.md index 68ad40879cf..5e93b451f49 100644 --- a/docs/c-runtime-library/reference/aligned-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-malloc-dbg.md @@ -34,22 +34,22 @@ Size of the requested memory allocation. 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. +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. +Line number in the source file where the allocation operation was requested or `NULL`. ## 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`](../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`** 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 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`** 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`](../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`. +**`_aligned_malloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -57,7 +57,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_malloc_dbg**|\| +|**`_aligned_malloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-malloc.md b/docs/c-runtime-library/reference/aligned-malloc.md index 8e50af2f891..42e0053649e 100644 --- a/docs/c-runtime-library/reference/aligned-malloc.md +++ b/docs/c-runtime-library/reference/aligned-malloc.md @@ -41,7 +41,7 @@ A pointer to the memory block that was allocated or `NULL` if the operation fail **`_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`](../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`. +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. diff --git a/docs/c-runtime-library/reference/aligned-msize-dbg.md b/docs/c-runtime-library/reference/aligned-msize-dbg.md index 16a56a0936f..ceb5c57f2c6 100644 --- a/docs/c-runtime-library/reference/aligned-msize-dbg.md +++ b/docs/c-runtime-library/reference/aligned-msize-dbg.md @@ -43,9 +43,9 @@ Returns the size (in bytes) as an unsigned integer. 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`](../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. +**`_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`* 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. +This function validates its parameter. If *`memblock`* is a null pointer or *`alignment`* isn't a power of 2, `_msize` invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -53,7 +53,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_msize_dbg**|\| +|**`_aligned_msize_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-msize.md b/docs/c-runtime-library/reference/aligned-msize.md index c445676d349..c73b2dd0e93 100644 --- a/docs/c-runtime-library/reference/aligned-msize.md +++ b/docs/c-runtime-library/reference/aligned-msize.md @@ -41,11 +41,11 @@ 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](/visualstudio/debugger/crt-debug-heap-details). -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. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -53,7 +53,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_msize**|\| +|**`_aligned_msize`**|\| For more compatibility information, see [Compatibility](../compatibility.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 5b324c42430..99f2817cbec 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md @@ -38,26 +38,26 @@ The alignment value, which must be an integer power of 2. 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**. +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**. +Line number in the source file where the allocation operation was requested or `NULL`. ## 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`](../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`** 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 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`** 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`](../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**. +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). @@ -67,7 +67,7 @@ For information about the allocation block types and how they're used, see [Type |Routine|Required header| |-------------|---------------------| -|**_aligned_offset_malloc_dbg**|\| +|**`_aligned_offset_malloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-offset-malloc.md b/docs/c-runtime-library/reference/aligned-offset-malloc.md index 35589da1976..82e664c283a 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc.md @@ -37,17 +37,17 @@ The offset into the memory allocation to force the alignment. ## 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 isn't 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`](../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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -55,7 +55,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_offset_malloc**|\| +|**`_aligned_offset_malloc`**|\| ## Example 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 17bb9bf5543..b335e614750 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md @@ -42,24 +42,24 @@ The alignment value, which must be an integer power of 2. 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**. +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**. +Line number in the source file where the **`aligned_offset_realloc`** operation was requested or `NULL`. ## 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. +**`_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`](../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. +**`_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 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. +`_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`](../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**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_realloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2 or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -67,7 +67,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_offset_realloc_dbg**|\| +|**`_aligned_offset_realloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-offset-realloc.md b/docs/c-runtime-library/reference/aligned-offset-realloc.md index 7db533145b7..d0bde6b25fd 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc.md @@ -41,17 +41,17 @@ The offset into the memory allocation to force the alignment. ## 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`** 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 isn't 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`](../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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -59,7 +59,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_offset_realloc**|\| +|**`_aligned_offset_realloc`**|\| ## Example 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 1d8e8342141..00815c22144 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md @@ -46,22 +46,22 @@ The alignment value, which must be an integer power of 2. 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**. +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**. +Line number in the source file where the realloc operation was requested or `NULL`. ## 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. +**`_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`](../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`** 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 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. +**`_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`](../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**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size (*`number`* * *`size`*) was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_recalloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to the requested *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -69,7 +69,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_offset_recalloc_dbg**|\| +|**`_aligned_offset_recalloc_dbg`**|\| ## See also diff --git a/docs/c-runtime-library/reference/aligned-offset-recalloc.md b/docs/c-runtime-library/reference/aligned-offset-recalloc.md index f37231b52c7..e6326a89b47 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc.md @@ -45,17 +45,17 @@ The offset into the memory allocation to force the alignment. ## 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`** 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 isn't 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`](../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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -63,7 +63,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_offset_recalloc**|\| +|**`_aligned_offset_recalloc`**|\| ## See also diff --git a/docs/c-runtime-library/reference/aligned-realloc-dbg.md b/docs/c-runtime-library/reference/aligned-realloc-dbg.md index 887174d6ed7..88c204d9913 100644 --- a/docs/c-runtime-library/reference/aligned-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-realloc-dbg.md @@ -38,26 +38,26 @@ The size of the requested memory allocation. 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**. +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**. +Line number in the source file where the `realloc` operation was requested or `NULL`. ## 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. +**`_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'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`](../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`** 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 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`** 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`](../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`* 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**. +Also, **`_aligned_realloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -65,7 +65,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_realloc_dbg**|\| +|**`_aligned_realloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-realloc.md b/docs/c-runtime-library/reference/aligned-realloc.md index 16b140a8c45..ff9cc1312f4 100644 --- a/docs/c-runtime-library/reference/aligned-realloc.md +++ b/docs/c-runtime-library/reference/aligned-realloc.md @@ -37,15 +37,15 @@ The alignment value, which must be an integer power of 2. ## 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. +**`_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'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`](../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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -53,7 +53,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_realloc**|\| +|**`_aligned_realloc`**|\| ## Example diff --git a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md index 577844e863b..31aa3a15f8d 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md @@ -42,26 +42,26 @@ The size in bytes of each element. 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**. +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**. +Line number in the source file where allocation operation was requested or `NULL`. ## 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. +**`_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'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`](../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`** 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 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`** 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`](../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`* 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**. +Also, **`_aligned_recalloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -69,7 +69,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_aligned_recalloc_dbg**|\| +|**`_aligned_recalloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/aligned-recalloc.md b/docs/c-runtime-library/reference/aligned-recalloc.md index 46cd00c62a0..176d3233e06 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc.md +++ b/docs/c-runtime-library/reference/aligned-recalloc.md @@ -41,15 +41,15 @@ The alignment value, which must be an integer power of 2. ## 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. +**`_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'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`](../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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -57,7 +57,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_aligned_recalloc**|\| +|**`_aligned_recalloc`**|\| ## See also diff --git a/docs/c-runtime-library/reference/alloca.md b/docs/c-runtime-library/reference/alloca.md index a5680b3fb5e..c2c6215f721 100644 --- a/docs/c-runtime-library/reference/alloca.md +++ b/docs/c-runtime-library/reference/alloca.md @@ -36,18 +36,18 @@ A stack overflow exception is generated if the space can't be allocated. The sta **`_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). diff --git a/docs/c-runtime-library/reference/amsg-exit.md b/docs/c-runtime-library/reference/amsg-exit.md index 1172f88a654..272f2ab0cf4 100644 --- a/docs/c-runtime-library/reference/amsg-exit.md +++ b/docs/c-runtime-library/reference/amsg-exit.md @@ -27,7 +27,7 @@ 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 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 8895c500622..f0187351cbd 100644 --- a/docs/c-runtime-library/reference/asctime-s-wasctime-s.md +++ b/docs/c-runtime-library/reference/asctime-s-wasctime-s.md @@ -58,36 +58,36 @@ Zero if successful. If there's a failure, the invalid parameter handler is invok |*`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| +|`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 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. +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 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)| +|`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`, `_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 *`numberOfElements`* should be at least this size. If it's 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). @@ -95,9 +95,9 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tasctime_s**|**asctime_s**|**asctime_s**|**_wasctime_s**| +|**`_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](../secure-template-overloads.md). @@ -105,18 +105,18 @@ In C++, using these functions is simplified by template overloads; the overloads |Routine|Required header| |-------------|---------------------| -|**asctime_s**|\| -|**_wasctime_s**|\ or \| +|**`asctime_s`**|\| +|**`_wasctime_s`**|\ or \| ## Security -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. +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 diff --git a/docs/c-runtime-library/reference/asctime-wasctime.md b/docs/c-runtime-library/reference/asctime-wasctime.md index 10002e8b28c..fd1a390a301 100644 --- a/docs/c-runtime-library/reference/asctime-wasctime.md +++ b/docs/c-runtime-library/reference/asctime-wasctime.md @@ -32,52 +32,52 @@ Time/date structure. ## 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. +**`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). -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. +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 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)| +|`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. 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`**. **`_wasctime`** and **`asctime`** behave identically otherwise. -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**. +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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tasctime**|**asctime**|**asctime**|**_wasctime**| +|`_tasctime`|**`asctime`**|**`asctime`**|**`_wasctime`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**asctime**|\| -|**_wasctime**|\ or \| +|**`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 diff --git a/docs/c-runtime-library/reference/asin-asinf-asinl.md b/docs/c-runtime-library/reference/asin-asinf-asinl.md index 14ded8f1e2d..c5bf4158751 100644 --- a/docs/c-runtime-library/reference/asin-asinf-asinl.md +++ b/docs/c-runtime-library/reference/asin-asinf-asinl.md @@ -38,9 +38,9 @@ By default, if *`x`* is less than -1 or greater than 1, **`asin`** returns an in |Input|SEH exception|`Matherr` exception| |-----------|-------------------|-----------------------| -|`± ∞`|**`INVALID`**|**`_DOMAIN`**| -|`± QNAN`, `IND`|none|**`_DOMAIN`**| -|`|x| > 1`|**`INVALID`**|**`_DOMAIN`**| +|`± ∞`|`INVALID`|`_DOMAIN`| +|`± QNAN`, `IND`|none|`_DOMAIN`| +|`|x| > 1`|`INVALID`|`_DOMAIN`| ## Remarks diff --git a/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md b/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md index 7a3a9ac3d66..00858723737 100644 --- a/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md +++ b/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md @@ -33,7 +33,7 @@ Floating-point value. ## Return value -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. +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| |-----------|-------------------|--------------------------| @@ -41,7 +41,7 @@ The **asinh** functions return the inverse hyperbolic sine (arc hyperbolic sine) ## 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](../tgmath.md) for details. @@ -51,7 +51,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required C header|Required C++ header| |--------------|--------------|------------------| -|**asinh**, **asinhf**, **asinhl**|\|\ or \| +|**`asinh`**, **`asinhf`**, **`asinhl`**|\|\ or \| |**asinh()** macro | \ || For additional compatibility information, see [Compatibility](../compatibility.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 b04f434fe03..c24bf84e0ea 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 @@ -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 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. +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); -```` +``` -**`_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 if 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). -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`**|``| +|`_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 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 afbcf16686b..c7b26da77ac 100644 --- a/docs/c-runtime-library/reference/assert-macro-assert-wassert.md +++ b/docs/c-runtime-library/reference/assert-macro-assert-wassert.md @@ -48,7 +48,7 @@ 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. @@ -72,7 +72,7 @@ For more information about CRT debugging, see [CRT debugging techniques](/visual 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`](../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 @@ -80,7 +80,7 @@ The `assert` macro is enabled in both the release and debug versions of the C ru |-------------|---------------------| |`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 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 990dac0bab5..d7a1069543a 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 @@ -46,7 +46,7 @@ Any numbers. |Input|SEH exception|`Matherr` exception| |-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| +|± QNAN, IND|none|`_DOMAIN`| ## Remarks diff --git a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md index dedb1c8c17b..8b2a3f9d16d 100644 --- a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md +++ b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md @@ -33,7 +33,7 @@ Floating-point value. ## Return value -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**. +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| |-----------|-------------------|-------------------------| @@ -42,7 +42,7 @@ The **atanh** functions return the inverse hyperbolic tangent (arc hyperbolic ta ## 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](../tgmath.md) for details. @@ -52,7 +52,7 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**atanh**, **atanhf**, **atanhl**|\|\ or \| +|**`atanh`**, **`atanhf`**, **`atanhl`**|\|\ or \| |**atanh()** macro | \ || For more compatibility information, see [Compatibility](../compatibility.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 332c57782e5..465f2fa2ed8 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 @@ -12,7 +12,7 @@ ms.assetid: 2d2530f4-4bd4-42e3-8083-f2d2fbc8432a --- # `_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 @@ -38,15 +38,15 @@ The locale to use. ## 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 don't generate floating-point code and don't 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 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 behavior, see [Global state in the CRT](../global-state.md). @@ -54,7 +54,7 @@ By default, this function's global state is scoped to the application. To change |Routines|Required header| |--------------|---------------------| -|**_atodbl**, **_atoldbl**, **_atoflt**

**_atodbl_l**, **_atoldbl_l**, **_atoflt_l**|\| +|**`_atodbl`**, **`_atoldbl`**, **`_atoflt`**

**`_atodbl_l`**, **`_atoldbl_l`**, **`_atoflt_l`**|\| ## Example 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 abbb7ee45f1..f9116341bba 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 @@ -45,7 +45,7 @@ Locale to use. 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](../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 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 72ae6da743b..b960cf1042d 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 @@ -45,7 +45,7 @@ Locale to use. 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. -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. +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 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 7ac2ae4fe8d..a4d6622394a 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 @@ -43,11 +43,11 @@ Locale to use. ## 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 can't 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. -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. +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](../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 @@ -55,35 +55,35 @@ 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 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`*] 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tstoi64**|**_atoi64**|**_atoi64**|**_wtoi64**| -|**_ttoi64**|**_atoi64**|**_atoi64**|**_wtoi64**| +|`_tstoi64`|**`_atoi64`**|**`_atoi64`**|**`_wtoi64`**| +|`_ttoi64`|**`_atoi64`**|**`_atoi64`**|**`_wtoi64`**| ## Requirements |Routines|Required header| |--------------|---------------------| -|**_atoi64**, **_atoi64_l**|\| -|**_wtoi64**, **_wtoi64_l**|\ or \| +|**`_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 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 10b6e692a7e..4a616139d13 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 @@ -44,7 +44,7 @@ Locale to use. 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. -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. +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 @@ -66,7 +66,7 @@ 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| +|`TCHAR.H` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_tstol`**|**`atol`**|**`atol`**|**`_wtol`**| |**`_ttol`**|**`atol`**|**`atol`**|**`_wtol`**| 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 368aeda6c83..da0034b19c3 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 @@ -43,11 +43,11 @@ Locale to use. ## 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 can't 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](../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 @@ -55,36 +55,36 @@ 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 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`*] 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tstoll**|**atoll**|**atoll**|**_wtoll**| -|**_tstoll_l**|**_atoll_l**|**_atoll_l**|**_wtoll_l**| -|**_ttoll**|**_atoll**|**_atoll**|**_wtoll**| +|`_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 \| +|**`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 diff --git a/docs/c-runtime-library/reference/beginthread-beginthreadex.md b/docs/c-runtime-library/reference/beginthread-beginthreadex.md index 1372f234a73..bc994136590 100644 --- a/docs/c-runtime-library/reference/beginthread-beginthreadex.md +++ b/docs/c-runtime-library/reference/beginthread-beginthreadex.md @@ -54,22 +54,22 @@ Start address of a routine that begins execution of a new thread. For **`_begint Stack size for a new thread, or 0. *`arglist`*\ -Argument list to be passed to a new thread, or **`NULL`**. +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 can't be inherited. +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 isn't specified, *`stack_size`* specifies the commit size. +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. +Points to a 32-bit variable that receives the thread identifier. If it's `NULL`, it's not used. ## 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](../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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -98,11 +98,11 @@ You can call [`_endthread`](endthread-endthreadex.md) or **`_endthreadex`** expl **`_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'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`**. +*`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, and also all newly created threads. For more information, see [Locale](../locale.md). @@ -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, 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. +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 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 44648db1d6e..325513f223f 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 @@ -49,23 +49,23 @@ Integer order of Bessel function. ## 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`**| +|`± 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`**| +|`± 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 behavior, see [Global state in the CRT](../global-state.md). @@ -73,7 +73,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_j0**, **_j1**, **_jn**, **_y0**, **_y1**, **_yn**|\ (C++), \ (C, C++)| +|**`_j0`**, **`_j1`**, **`_jn`**, **`_y0`**, **`_y1`**, **`_yn`**|\ (C++), \ (C, C++)| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/bsearch-s.md b/docs/c-runtime-library/reference/bsearch-s.md index e2fc264ab07..b0bc1ff4451 100644 --- a/docs/c-runtime-library/reference/bsearch-s.md +++ b/docs/c-runtime-library/reference/bsearch-s.md @@ -49,22 +49,22 @@ 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`* 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. +**`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](../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). +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| +|*`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**| +|`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| |-----------------------------------------|-----------------| @@ -72,7 +72,7 @@ The **bsearch_s** function performs a binary search of a sorted array of *`numbe |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 the 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 behavior, see [Global state in the CRT](../global-state.md). @@ -80,7 +80,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**bsearch_s**|\ and \| +|**`bsearch_s`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/bsearch.md b/docs/c-runtime-library/reference/bsearch.md index fc6cc419564..de2f0f7b7b0 100644 --- a/docs/c-runtime-library/reference/bsearch.md +++ b/docs/c-runtime-library/reference/bsearch.md @@ -45,11 +45,11 @@ Callback function that compares two elements. The first is a pointer to the key ## Return value -**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. +**`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| |-----------------------------------------|-----------------| @@ -57,7 +57,7 @@ The **bsearch** function performs a binary search of a sorted array of *`number` |`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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -65,7 +65,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**bsearch**|\ and \| +|**`bsearch`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/btowc.md b/docs/c-runtime-library/reference/btowc.md index a16459cf2ee..864197406a7 100644 --- a/docs/c-runtime-library/reference/btowc.md +++ b/docs/c-runtime-library/reference/btowc.md @@ -29,7 +29,7 @@ Integer to test. ## 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 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. +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 @@ -39,7 +39,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**btowc**|\ or \| +|**`btowc`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md b/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md index ace1d80a074..6bf22acd744 100644 --- a/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md +++ b/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md @@ -38,17 +38,17 @@ Pointer to an array to store the converted UTF-8 multibyte character. A wide character to convert. *`state`*\ -A pointer to an **mbstate_t** object. +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`*. @@ -60,7 +60,7 @@ To convert UTF-16 characters into non-UTF-8 multibyte characters, use the [`wcst |Routine|Required header| |-------------|---------------------| -|**c16rtomb**, **c32rtomb**|C, C++: \| +|**`c16rtomb`**, **`c32rtomb`**|C, C++: \| For compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md b/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md index 6f7000973ce..93fd231b576 100644 --- a/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md +++ b/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md @@ -45,13 +45,13 @@ 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**|\|\| +|**`cabs`**, **`cabsf`**, **`cabsl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cabs.md b/docs/c-runtime-library/reference/cabs.md index bd72a360b24..955c2fe6197 100644 --- a/docs/c-runtime-library/reference/cabs.md +++ b/docs/c-runtime-library/reference/cabs.md @@ -29,11 +29,11 @@ Complex number. ## 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`](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_cabs**|\| +|**`_cabs`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md b/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md index 8cdaaff929e..9828639f31c 100644 --- a/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md +++ b/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md @@ -38,13 +38,13 @@ The arc cosine of *`z`*, in radians. The result is unbounded along the imaginary ## 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**|\|\| +|**`cacos`**, **`cacosf`**, **`cacosl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md b/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md index 838c1e21c0f..618efebe7df 100644 --- a/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md +++ b/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md @@ -45,13 +45,13 @@ The inverse hyperbolic cosine of *`z`*, in radians. The result is unbounded and ## 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**|\|\| +|**`cacosh`**, **`cacoshf`**, **`cacoshl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/calloc-dbg.md b/docs/c-runtime-library/reference/calloc-dbg.md index 801ec33e1a8..adb15a11d47 100644 --- a/docs/c-runtime-library/reference/calloc-dbg.md +++ b/docs/c-runtime-library/reference/calloc-dbg.md @@ -35,25 +35,25 @@ Requested number of memory blocks. Requested size of each memory block (bytes). *`blockType`*\ -Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. For information about the allocation block types and how they're used, see[Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). *`filename`*\ -Pointer to name of the source file that requested allocation operation or **NULL**. +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**. +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`](../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 -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`](../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: +**`_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. @@ -61,9 +61,9 @@ On successful completion, this function returns a pointer to the user portion of - *`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 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`** 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`](../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 and the debug version, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). @@ -71,7 +71,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_calloc_dbg**|\| +|**`_calloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/calloc.md b/docs/c-runtime-library/reference/calloc.md index 36e314d8590..bf6c646cc1b 100644 --- a/docs/c-runtime-library/reference/calloc.md +++ b/docs/c-runtime-library/reference/calloc.md @@ -38,7 +38,7 @@ Length in bytes of each element. 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`](../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. diff --git a/docs/c-runtime-library/reference/carg-cargf-cargl.md b/docs/c-runtime-library/reference/carg-cargf-cargl.md index 9af11140377..20efea1ace2 100644 --- a/docs/c-runtime-library/reference/carg-cargf-cargl.md +++ b/docs/c-runtime-library/reference/carg-cargf-cargl.md @@ -46,7 +46,7 @@ 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](../tgmath.md) for details. @@ -54,8 +54,8 @@ If you use the \ `carg()` macro, the type of the argument determines w |Routine|C header|C++ header| |-------------|--------------|------------------| -|**carg**, **cargf**, **cargl**|\|\| -|**carg** macro | \ || +|**`carg`**, **`cargf`**, **`cargl`**|\|\| +|**`carg`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/casin-casinf-casinl.md b/docs/c-runtime-library/reference/casin-casinf-casinl.md index 32ec935af88..fda418be33e 100644 --- a/docs/c-runtime-library/reference/casin-casinf-casinl.md +++ b/docs/c-runtime-library/reference/casin-casinf-casinl.md @@ -45,13 +45,13 @@ The arcsine of *`z`*, in radians. The result is unbounded along the imaginary ax ## 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**|\|\| +|**`casin`**, **`casinf`**, **`casinl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md b/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md index d6ed62adc47..fc391657ec0 100644 --- a/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md +++ b/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md @@ -45,13 +45,13 @@ The inverse hyperbolic sine of *`z`*, in radians. The result is unbound along th ## 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**|\|\| +|**`casinh`**, **`casinhf`**, **`casinhl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/catan-catanf-catanl.md b/docs/c-runtime-library/reference/catan-catanf-catanl.md index af8ad547271..b97babc7470 100644 --- a/docs/c-runtime-library/reference/catan-catanf-catanl.md +++ b/docs/c-runtime-library/reference/catan-catanf-catanl.md @@ -38,13 +38,13 @@ The arctangent of *`z`*, in radians. The result is unbounded along the imaginary ## 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**|\|\| +|**`catan`**, **`catanf`**, **`catanl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md b/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md index b616feb3757..ea5d017eee3 100644 --- a/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md +++ b/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md @@ -45,13 +45,13 @@ The inverse hyperbolic tangent of *`z`*, in radians. The result is unbounded alo ## 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**|\|\| +|**`catanh`**, **`catanhf`**, **`catanhl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md b/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md index 1d16ddfb964..957e47536fb 100644 --- a/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md +++ b/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md @@ -42,15 +42,15 @@ Floating-point 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| +|Input|SEH Exception|`_matherr` Exception| |-----------|-------------------|--------------------------| |± ∞, 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](../tgmath.md) for details. @@ -60,8 +60,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**cbrt**, **cbrtf**, **cbrtl**|\|\| -|**cbrt** macro | \ || +|**`cbrt`**, **`cbrtf`**, **`cbrtl`**|\|\| +|**`cbrt`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md b/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md index 84892ecdfab..0fe4d779d6a 100644 --- a/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md +++ b/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md @@ -31,19 +31,19 @@ The imaginary part of the complex number to construct. ## 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**|\|\| +|**`_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](../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 diff --git a/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md b/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md index c8d4c0aae0a..6f2aa2cdbf2 100644 --- a/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md +++ b/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md @@ -45,13 +45,13 @@ 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**|\|\| +|**`ccos`**, **`ccosf`**, **`ccosl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md b/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md index 40868d04023..68e83f1a303 100644 --- a/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md +++ b/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md @@ -45,13 +45,13 @@ 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**|\|\| +|**`ccosh`**, **`ccoshf`**, **`ccoshl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ceil-ceilf-ceill.md b/docs/c-runtime-library/reference/ceil-ceilf-ceill.md index dfb9ec0ef82..11de4191c67 100644 --- a/docs/c-runtime-library/reference/ceil-ceilf-ceill.md +++ b/docs/c-runtime-library/reference/ceil-ceilf-ceill.md @@ -42,17 +42,17 @@ Floating-point 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**| +|± `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](../tgmath.md) for details. @@ -62,8 +62,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -| **ceil**, **ceilf**, **ceill**| \ | -| **ceil** macro | \ | +| **`ceil`**, **`ceilf`**, **`ceill`**| \ | +| **`ceil`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cexit-c-exit.md b/docs/c-runtime-library/reference/cexit-c-exit.md index 55171ba9dd0..c7fb4a44eb2 100644 --- a/docs/c-runtime-library/reference/cexit-c-exit.md +++ b/docs/c-runtime-library/reference/cexit-c-exit.md @@ -23,16 +23,16 @@ 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 doesn't terminate process.| -|**_c_exit**|Performs quick C library termination procedures and returns to caller, but doesn't terminate process.| +|`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 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: +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( ); @@ -44,8 +44,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_cexit**|\| -|**_c_exit**|\| +|**`_cexit`**|\| +|**`_c_exit`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md b/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md index 4f84bab2618..3cb594d03f2 100644 --- a/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md +++ b/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md @@ -36,13 +36,13 @@ 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**|\|\| +|**`cexp`**, **`cexpf`**, **`cexpl`**|\|\| For compatibility information, see [Compatibility](../compatibility.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 63e680325da..a2058bed4d5 100644 --- a/docs/c-runtime-library/reference/cgets-s-cgetws-s.md +++ b/docs/c-runtime-library/reference/cgets-s-cgetws-s.md @@ -61,15 +61,15 @@ The return value is zero if successful; otherwise, an error code if a failure oc |*`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| +|`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](../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, 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). @@ -79,16 +79,16 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_cgetts_s**|**_cgets_s**|**_cgets_s**|**_cgetws_s**| +|`_cgetts_s`|**`_cgets_s`**|**`_cgets_s`**|**`_cgetws_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_cgets_s**|\| -|**_cgetws_s**|\ or \| +|**`_cgets_s`**|\| +|**`_cgetws_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/chdir-wchdir.md b/docs/c-runtime-library/reference/chdir-wchdir.md index 76ee1bb0d00..0b2e6ea3057 100644 --- a/docs/c-runtime-library/reference/chdir-wchdir.md +++ b/docs/c-runtime-library/reference/chdir-wchdir.md @@ -31,7 +31,7 @@ Path of new working directory. ## 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](../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 @@ -49,7 +49,7 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mapping -|`Tchar.h` routine|`_UNICODE and _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| +|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| |**`_tchdir`**|**`_chdir`**|**`_chdir`**|**`_wchdir`**| diff --git a/docs/c-runtime-library/reference/chdrive.md b/docs/c-runtime-library/reference/chdrive.md index 1ede393f4e7..6fbcdc5b9a4 100644 --- a/docs/c-runtime-library/reference/chdrive.md +++ b/docs/c-runtime-library/reference/chdrive.md @@ -36,11 +36,11 @@ Zero (0) if the current working drive was changed successfully; otherwise, -1. ## Remarks -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**. +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 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 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 behavior, see [Global state in the CRT](../global-state.md). @@ -48,7 +48,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_chdrive**|\| +|**`_chdrive`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md b/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md index 4caf4fa0109..f5e803bf944 100644 --- a/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md +++ b/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md @@ -35,14 +35,14 @@ The floating-point value to be changed. ## 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**|\| +|**`_chgsign`**|\| +|**`_chgsignf`**, **`_chgsignl`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/chmod-wchmod.md b/docs/c-runtime-library/reference/chmod-wchmod.md index 8074a8e75c0..ff5abefbce9 100644 --- a/docs/c-runtime-library/reference/chmod-wchmod.md +++ b/docs/c-runtime-library/reference/chmod-wchmod.md @@ -31,11 +31,11 @@ Permission setting for the file. ## 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,24 +45,24 @@ 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](../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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tchmod**|**_chmod**|**_chmod**|**_wchmod**| +|`_tchmod`|**`_chmod`**|**`_chmod`**|**`_wchmod`**| ## Requirements |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_chmod**|\|\, \, \| -|**_wchmod**|\ or \|\, \, \| +|**`_chmod`**|\|\, \, \| +|**`_wchmod`**|\ or \|\, \, \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/chsize-s.md b/docs/c-runtime-library/reference/chsize-s.md index 046bbb04034..527a87840bc 100644 --- a/docs/c-runtime-library/reference/chsize-s.md +++ b/docs/c-runtime-library/reference/chsize-s.md @@ -33,15 +33,15 @@ New length of the file in bytes. ## 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 [`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`* 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). @@ -51,7 +51,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_chsize_s**|\|\| +|**`_chsize_s`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/chsize.md b/docs/c-runtime-library/reference/chsize.md index 1dbfa560770..fe5eccbe1db 100644 --- a/docs/c-runtime-library/reference/chsize.md +++ b/docs/c-runtime-library/reference/chsize.md @@ -33,13 +33,13 @@ New length of the file in bytes. ## 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. 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](../parameter-validation.md). @@ -49,7 +49,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_chsize**|\|\| +|**`_chsize`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md b/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md index de631bd6522..23fd3ab185a 100644 --- a/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md +++ b/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md @@ -37,7 +37,7 @@ 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](../tgmath.md) for details. @@ -45,8 +45,8 @@ If you use the \ `cimag()` macro, the type of the argument determines |Routine|C header|C++ header| |-------------|--------------|------------------| -|**cimag**, **cimagf**, **cimagl**|\|\| -|**cimag** macro | \ || +|**`cimag`**, **`cimagf`**, **`cimagl`**|\|\| +|**`cimag`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/clear87-clearfp.md b/docs/c-runtime-library/reference/clear87-clearfp.md index 1b3aaddaea0..289dd1f6154 100644 --- a/docs/c-runtime-library/reference/clear87-clearfp.md +++ b/docs/c-runtime-library/reference/clear87-clearfp.md @@ -23,13 +23,13 @@ unsigned int _clearfp( void ); ## 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'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**. +**`_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. @@ -37,8 +37,8 @@ These functions are deprecated when compiling with [/clr (Common Language Runtim |Routine|Required header| |-------------|---------------------| -|**_clear87**|\| -|**_clearfp**|\| +|**`_clear87`**|\| +|**`_clearfp`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/clearerr-s.md b/docs/c-runtime-library/reference/clearerr-s.md index 139da3bd392..8a1c47bb633 100644 --- a/docs/c-runtime-library/reference/clearerr-s.md +++ b/docs/c-runtime-library/reference/clearerr-s.md @@ -25,17 +25,17 @@ errno_t clearerr_s( ### Parameters *`stream`*\ -Pointer to **FILE** structure +Pointer to `FILE` structure ## 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 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. +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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**clearerr_s**|\| +|**`clearerr_s`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/clearerr.md b/docs/c-runtime-library/reference/clearerr.md index 713b2e1a27e..23cd055b400 100644 --- a/docs/c-runtime-library/reference/clearerr.md +++ b/docs/c-runtime-library/reference/clearerr.md @@ -25,13 +25,13 @@ void clearerr( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## Remarks -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. +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](../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). +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). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**clearerr**|\| +|**`clearerr`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/clock.md b/docs/c-runtime-library/reference/clock.md index 94f4a125f50..ee56c71453d 100644 --- a/docs/c-runtime-library/reference/clock.md +++ b/docs/c-runtime-library/reference/clock.md @@ -21,13 +21,13 @@ clock_t clock( void ); ## 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. 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`**. +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 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. +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 diff --git a/docs/c-runtime-library/reference/clog-clogf-clogl.md b/docs/c-runtime-library/reference/clog-clogf-clogl.md index b5df0162053..327fc684dea 100644 --- a/docs/c-runtime-library/reference/clog-clogf-clogl.md +++ b/docs/c-runtime-library/reference/clog-clogf-clogl.md @@ -55,13 +55,13 @@ The possible return values are: ## 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**|\|\| +|**`clog`**, **`clogf`**, **`clogl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md b/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md index 8e7e5b6e3ba..48aa3f9b456 100644 --- a/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md +++ b/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md @@ -46,13 +46,13 @@ The possible return values are: ## 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**|\|\| +|**`clog10`**, **`clog10f`**, **`clog10l`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/close.md b/docs/c-runtime-library/reference/close.md index acbf5ac6eae..cb833dc5afa 100644 --- a/docs/c-runtime-library/reference/close.md +++ b/docs/c-runtime-library/reference/close.md @@ -29,15 +29,15 @@ File descriptor referring to the open file. ## 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 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**. +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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -45,7 +45,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_close**|\|\| +|**`_close`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md b/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md index 08ed4f6d08e..6318565ee01 100644 --- a/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md +++ b/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md @@ -31,19 +31,19 @@ The other complex operand to multiply. ## 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 don't 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**|\|\| +|**`_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](../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 diff --git a/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md b/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md index 4e7c94b6f50..1439ab57a18 100644 --- a/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md +++ b/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md @@ -31,19 +31,19 @@ The floating-point operand to multiply. ## Return value -A **_Dcomplex**, **_Fcomplex**, or **_Lcomplex** structure that represents the complex product of the complex number *`x`* and floating-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 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. +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**|\|\| +|**`_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](../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 diff --git a/docs/c-runtime-library/reference/commit.md b/docs/c-runtime-library/reference/commit.md index b8ddfbc8cb6..8db999d572e 100644 --- a/docs/c-runtime-library/reference/commit.md +++ b/docs/c-runtime-library/reference/commit.md @@ -29,13 +29,13 @@ File descriptor referring to the open file. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional headers| |-------------|---------------------|----------------------| -|**_commit**|\|\| +|**`_commit`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/configthreadlocale.md b/docs/c-runtime-library/reference/configthreadlocale.md index 83d92dfc61c..dde64b270ec 100644 --- a/docs/c-runtime-library/reference/configthreadlocale.md +++ b/docs/c-runtime-library/reference/configthreadlocale.md @@ -27,7 +27,7 @@ The option to set. One of the options listed in the following table. ## 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,15 +35,15 @@ 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, 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](../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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/conj-conjf-conjl.md b/docs/c-runtime-library/reference/conj-conjf-conjl.md index 0a532afd66e..37161eda8e6 100644 --- a/docs/c-runtime-library/reference/conj-conjf-conjl.md +++ b/docs/c-runtime-library/reference/conj-conjf-conjl.md @@ -46,7 +46,7 @@ The complex conjugate of *`z`*. The result has the same real and imaginary par ## 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](../tgmath.md) for details. @@ -54,8 +54,8 @@ If you use the \ `conj()` macro, the type of the argument determines w |Routine|C header|C++ header| |-------------|--------------|------------------| -|**conj**, **conjf**, **conjl**|\|\| -|**conj** macro | \ || +|**`conj`**, **`conjf`**, **`conjl`**|\|\| +|**`conj`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.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 bcf99a697c8..2d054af5f80 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,9 +83,9 @@ _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](../parameter-validation.md). @@ -96,15 +96,15 @@ 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| +|`_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 diff --git a/docs/c-runtime-library/reference/controlfp-s.md b/docs/c-runtime-library/reference/controlfp-s.md index cef03a70522..2b7ff50f02b 100644 --- a/docs/c-runtime-library/reference/controlfp-s.md +++ b/docs/c-runtime-library/reference/controlfp-s.md @@ -36,7 +36,7 @@ Mask for new control-word bits to set. ## 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,11 +75,11 @@ _controlfp_s(¤t_word, _DN_FLUSH, _MCW_DN); // and x64 processors with SSE2 support. Ignored on other x86 platforms. ``` -On ARM platforms, the **`_controlfp_s`** function applies to the FPSCR register. On x64 architectures, only the SSE2 control word that's stored in the MXCSR register is affected. On Intel (x86) platforms, **`_controlfp_s`** affects the control words for both the x87 and the SSE2, if present. It's possible for the two control words to be inconsistent with each other (because of a previous call to [`__control87_2`](control87-controlfp-control87-2.md), for example); if there's an inconsistency between the two control words, **`_controlfp_s`** sets the **`EM_AMBIGUOUS`** flag in *`currentControl`*. It's a warning that the returned control word might not represent the state of both floating-point control words accurately. +On ARM platforms, the **`_controlfp_s`** function applies to the FPSCR register. On x64 architectures, only the SSE2 control word that's stored in the MXCSR register is affected. On Intel (x86) platforms, **`_controlfp_s`** affects the control words for both the x87 and the SSE2, if present. It's possible for the two control words to be inconsistent with each other (because of a previous call to [`__control87_2`](control87-controlfp-control87-2.md), for example); if there's an inconsistency between the two control words, **`_controlfp_s`** sets the `EM_AMBIGUOUS` flag in *`currentControl`*. It's a warning that the returned control word might not represent the state of both floating-point control words accurately. On the ARM and x64 architectures, changing the infinity mode or the floating-point precision isn't supported. If the precision control mask is used on the x64 platform, the function raises an assertion and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -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`**. +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`. 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. @@ -87,15 +87,15 @@ By default, this function's global state is scoped to the application. To change ### 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| +|`_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 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 c316d68492b..5d13cdafd3d 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 @@ -60,11 +60,11 @@ The floating-point value that's returned as the sign of the result. ## 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](../tgmath.md) for details. @@ -72,9 +72,9 @@ If you use the \ `copysign()` macro, the type of the argument determin |Routine|Required header| |-------------|---------------------| -|**_copysign**|\| -|**copysign**, **copysignf**, **copysignl**, **_copysignf**, **_copysignl**|\| -|**copysign** macro | \ | +|**`_copysign`**|\| +|**`copysign`**, **`copysignf`**, **`copysignl`**, **`_copysignf`**, **`_copysignl`**|\| +|**`copysign`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cos-cosf-cosl.md b/docs/c-runtime-library/reference/cos-cosf-cosl.md index c8d5b485bc7..da59b19aed3 100644 --- a/docs/c-runtime-library/reference/cos-cosf-cosl.md +++ b/docs/c-runtime-library/reference/cos-cosf-cosl.md @@ -37,12 +37,12 @@ The cosine of *`x`*. If *`x`* is greater than or equal to 263, or less than or e |Input|SEH Exception|`Matherr` Exception| |-----------|-------------------|-----------------------| -|± QNAN, IND|none|**_DOMAIN**| -|± INF|**INVALID**|**_DOMAIN**| +|± 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](../tgmath.md) for details. @@ -52,7 +52,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required C header|Required C++ header| |-------------|---------------------|-| -|**cos**, **cosh**, **cosf**|\|\ or \| +|**`cos`**, **`cosh`**, **`cosf`**|\|\ or \| |**cos()** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cosh-coshf-coshl.md b/docs/c-runtime-library/reference/cosh-coshf-coshl.md index 40b8c7a2727..12f5ca3d9cc 100644 --- a/docs/c-runtime-library/reference/cosh-coshf-coshl.md +++ b/docs/c-runtime-library/reference/cosh-coshf-coshl.md @@ -34,12 +34,12 @@ Angle in radians. 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`**| +|± QNAN, IND|none|`_DOMAIN`| +|*`x`* ≥ 7.104760e+002|`INEXACT`+`OVERFLOW`|`OVERFLOW`| ## Remarks diff --git a/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md b/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md index 7603a076dd8..d81aef6d0f1 100644 --- a/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md +++ b/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md @@ -48,13 +48,13 @@ The value of *`x`* raised to the power of *`y`* with a branch cut for *`x`* alon ## 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**|\|\| +|**`cpow`**, **`cpowf`**, **`cpowl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.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 0f5d4621019..f184719a092 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 @@ -52,13 +52,13 @@ 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](../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. +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](../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. @@ -67,17 +67,17 @@ The versions of these functions with the **_l** suffix are identical except that ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcprintf**|**_cprintf**|**_cprintf**|**_cwprintf**| -|**_tcprintf_l**|**_cprintf_l**|**_cprintf_l**|**_cwprintf_l**| +|`_tcprintf`|**`_cprintf`**|**`_cprintf`**|**`_cwprintf`**| +|`_tcprintf_l`|**`_cprintf_l`**|**`_cprintf_l`**|**`_cwprintf_l`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_cprintf**, **_cprintf_l**|\| -|**_cwprintf**, **_cwprintf_l**|\| +|**`_cprintf`**, **`_cprintf_l`**|\| +|**`_cwprintf`**, **`_cwprintf_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 b51985da055..b83296c379c 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 @@ -56,13 +56,13 @@ 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`](../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). +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, **_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. +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](../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. @@ -72,17 +72,17 @@ Also, like **_cprintf_s** and **_cwprintf_s**, they validate the input pointer a ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcprintf_p**|**_cprintf_p**|**_cprintf_p**|**_cwprintf_p**| -|**_tcprintf_p_l**|**_cprintf_p_l**|**_cprintf_p_l**|**_cwprintf_p_l**| +|`_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**|\| +|**`_cprintf_p`**, **`_cprintf_p_l`**|\| +|**`_cwprintf_p`**, **`_cwprintf_p_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 b4dc3c97fcf..5678b7a6729 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 @@ -56,32 +56,32 @@ 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`](../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. +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. > > 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](../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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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**|\| +|**`_cprintf_s`**, **`_cprintf_s_l`**|\| +|**`_cwprintf_s`**, **`_cwprintf_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md b/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md index 58b310f5226..7105b710a2c 100644 --- a/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md +++ b/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md @@ -46,7 +46,7 @@ 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](../tgmath.md) for details. @@ -54,8 +54,8 @@ If you use the \ `cproj()` macro, the type of the argument determines |Routine|C header|C++ header| |-------------|--------------|------------------| -|**cproj**, **cprojf**, **cprojl**|\|\| -|**cproj** macro | \ || +|**`cproj`**, **`cprojf`**, **`cprojl`**|\|\| +|**`cproj`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cputs-cputws.md b/docs/c-runtime-library/reference/cputs-cputws.md index e504220aa25..d288a4dc2a5 100644 --- a/docs/c-runtime-library/reference/cputs-cputws.md +++ b/docs/c-runtime-library/reference/cputs-cputws.md @@ -35,28 +35,28 @@ Output string. ## 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 isn't 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_cputts**|**_cputs**|**_cputs**|**_cputws**| +|`_cputts`|**`_cputs`**|**`_cputs`**|**`_cputws`**| ## Requirements |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_cputs**|\|\| -|**_cputws**|\|\| +|**`_cputs`**|\|\| +|**`_cputws`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/creal-crealf-creall.md b/docs/c-runtime-library/reference/creal-crealf-creall.md index e40bf572288..f078b382778 100644 --- a/docs/c-runtime-library/reference/creal-crealf-creall.md +++ b/docs/c-runtime-library/reference/creal-crealf-creall.md @@ -37,7 +37,7 @@ 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](../tgmath.md) for details. @@ -45,10 +45,10 @@ If you use the \ `creal()` macro, the type of the argument determines |Routine|C header|C++ header| |-------------|--------------|------------------| -|**creal**, **crealf**, **creall**|\|\| -|**creal** macro | \ || +|**`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](../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 diff --git a/docs/c-runtime-library/reference/creat-wcreat.md b/docs/c-runtime-library/reference/creat-wcreat.md index aa59c5a1ad7..10ac46fc6f3 100644 --- a/docs/c-runtime-library/reference/creat-wcreat.md +++ b/docs/c-runtime-library/reference/creat-wcreat.md @@ -12,7 +12,7 @@ ms.assetid: 3b3b795d-1620-40ec-bd2b-a4bbb0d20fe5 --- # `_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 @@ -37,31 +37,31 @@ Permission setting. ## 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| +|`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.| +|`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](../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 [`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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcreat**|**_creat**|**_creat**|**_wcreat**| +|`_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| |-----------|----------------| @@ -69,16 +69,16 @@ If the file specified by *`filename`* doesn't exist, a new file is created with |`_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 \|\, \, \| +|**`_creat`**|\|\, \, \| +|**`_wcreat`**|\ or \|\, \, \| For more compatibility information, see [Compatibility](../compatibility.md). 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 abe2972b9dd..1159285cd5c 100644 --- a/docs/c-runtime-library/reference/create-locale-wcreate-locale.md +++ b/docs/c-runtime-library/reference/create-locale-wcreate-locale.md @@ -37,34 +37,34 @@ Locale specifier. ## Return value -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. +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's 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: | *`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 isn't 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](../locale-names-languages-and-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). +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). -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 behavior, see [Global state in the CRT](../global-state.md). @@ -72,8 +72,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_create_locale**|\| -|**_wcreate_locale**|\ or \| +|**`_create_locale`**|\| +|**`_wcreate_locale`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtcheckmemory.md b/docs/c-runtime-library/reference/crtcheckmemory.md index 4be89d4bb71..1cfdb4d295f 100644 --- a/docs/c-runtime-library/reference/crtcheckmemory.md +++ b/docs/c-runtime-library/reference/crtcheckmemory.md @@ -23,27 +23,27 @@ int _CrtCheckMemory( void ); ## 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`](../debug.md) isn't 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`](../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**. +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 basic 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](/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). ## Requirements |Routine|Required header| |-------------|---------------------| -|**_CrtCheckMemory**|\| +|**`_CrtCheckMemory`**|\| For more compatibility information, see [Compatibility](../compatibility.md). @@ -53,7 +53,7 @@ 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 diff --git a/docs/c-runtime-library/reference/crtdbgbreak.md b/docs/c-runtime-library/reference/crtdbgbreak.md index dd294360a87..aef08343937 100644 --- a/docs/c-runtime-library/reference/crtdbgbreak.md +++ b/docs/c-runtime-library/reference/crtdbgbreak.md @@ -26,7 +26,7 @@ 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). @@ -34,7 +34,7 @@ For more information about using other hook-capable run-time functions and writi |Routine|Required header| |-------------|---------------------| -|**_CrtDbgBreak**|\| +|**`_CrtDbgBreak`**|\| ## Libraries diff --git a/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md b/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md index dab31f01f57..67f71e9dd06 100644 --- a/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md +++ b/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md @@ -38,13 +38,13 @@ int _CrtDbgReportW( ### Parameters *`reportType`*\ -Report type: **_CRT_WARN**, **_CRT_ERROR**, and **_CRT_ASSERT**. +Report type: `_CRT_WARN`, `_CRT_ERROR`, and `_CRT_ASSERT`. *`filename`*\ -Pointer to name of source file where assert/report occurred or **NULL**. +Pointer to name of source file where assert/report occurred or `NULL`. *`lineNumber`*\ -Line number in source file where assert/report occurred or **NULL**. +Line number in source file where assert/report occurred or `NULL`. *`moduleName`*\ Pointer to name of module (.exe or .dll) where assert or report occurred. @@ -57,41 +57,41 @@ Optional substitution arguments used by *`format`*. ## 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 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. +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, 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. +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'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. +**`_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's 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| +|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**.| +|`_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). -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**|\| +|**`_CrtDbgReport`**|\| +|**`_CrtDbgReportW`**|\| -**_CrtDbgReport** and **_CrtDbgReportW** are Microsoft extensions. For more information, see [Compatibility](../compatibility.md). +**`_CrtDbgReport`** and **`_CrtDbgReportW`** are Microsoft extensions. For more information, see [Compatibility](../compatibility.md). ## Libraries diff --git a/docs/c-runtime-library/reference/crtdoforallclientobjects.md b/docs/c-runtime-library/reference/crtdoforallclientobjects.md index 85c9dcbe770..23619fffda5 100644 --- a/docs/c-runtime-library/reference/crtdoforallclientobjects.md +++ b/docs/c-runtime-library/reference/crtdoforallclientobjects.md @@ -12,7 +12,7 @@ ms.assetid: d0fdb835-3cdc-45f1-9a21-54208e8df248 --- # `_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 @@ -26,26 +26,26 @@ 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**. +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`*\ 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`](../crtdbgflag.md) flag isn't turned on, **_CrtDoForAllClientObjects** immediately returns. When [`_DEBUG`](../debug.md) isn't 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](/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). -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. +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**|\, \| +|**`_CrtDoForAllClientObjects`**|\, \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtdumpmemoryleaks.md b/docs/c-runtime-library/reference/crtdumpmemoryleaks.md index 0295e810f28..26843ff4e18 100644 --- a/docs/c-runtime-library/reference/crtdumpmemoryleaks.md +++ b/docs/c-runtime-library/reference/crtdumpmemoryleaks.md @@ -28,11 +28,11 @@ int _CrtDumpMemoryLeaks( void ); 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`](../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). diff --git a/docs/c-runtime-library/reference/crtgetallochook.md b/docs/c-runtime-library/reference/crtgetallochook.md index 6e39542537f..75253914f1d 100644 --- a/docs/c-runtime-library/reference/crtgetallochook.md +++ b/docs/c-runtime-library/reference/crtgetallochook.md @@ -26,7 +26,7 @@ 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). @@ -34,7 +34,7 @@ For more information about using other hook-capable run-time functions and writi |Routine|Required header| |-------------|---------------------| -|**_CrtGetAllocHook**|\| +|**`_CrtGetAllocHook`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtgetdumpclient.md b/docs/c-runtime-library/reference/crtgetdumpclient.md index ad86bd5874d..ed82cb9bb31 100644 --- a/docs/c-runtime-library/reference/crtgetdumpclient.md +++ b/docs/c-runtime-library/reference/crtgetdumpclient.md @@ -12,7 +12,7 @@ ms.assetid: 9051867f-341b-493b-b53d-45d2b454a3ad --- # `_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 @@ -26,7 +26,7 @@ Returns the current dump routine. ## Remarks -The **_CrtGetDumpClient** function retrieves the current hook function for dumping objects stored in the **_CLIENT_BLOCK** memory blocks. +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). @@ -34,7 +34,7 @@ For more information about using other hook-capable run-time functions and writi |Routine|Required header| |-------------|---------------------| -|**_CrtGetDumpClient**|\| +|**`_CrtGetDumpClient`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtgetreporthook.md b/docs/c-runtime-library/reference/crtgetreporthook.md index f1223044a56..f8480b441db 100644 --- a/docs/c-runtime-library/reference/crtgetreporthook.md +++ b/docs/c-runtime-library/reference/crtgetreporthook.md @@ -26,7 +26,7 @@ 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). @@ -34,7 +34,7 @@ For more information about using other hook-capable run-time functions and writi |Routine|Required header| |-------------|---------------------| -|**_CrtGetReportHook**|\| +|**`_CrtGetReportHook`**|\| For more compatibility information, see [Compatibility](../compatibility.md). @@ -44,7 +44,7 @@ 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 diff --git a/docs/c-runtime-library/reference/crtismemoryblock.md b/docs/c-runtime-library/reference/crtismemoryblock.md index f59bc6089de..db2681efc50 100644 --- a/docs/c-runtime-library/reference/crtismemoryblock.md +++ b/docs/c-runtime-library/reference/crtismemoryblock.md @@ -35,38 +35,38 @@ Pointer to the beginning of the memory block to verify. Size of the specified block (in bytes). *`requestNumber`*\ -Pointer to the allocation number of the block or **NULL**. +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**. +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**. +Pointer to the line number in the source file or `NULL`. ## 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. 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. +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 basic 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( _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](/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). ## Requirements |Routine|Required header| |-------------|---------------------| -|**_CrtIsMemoryBlock**|\| +|**`_CrtIsMemoryBlock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtisvalidpointer.md b/docs/c-runtime-library/reference/crtisvalidpointer.md index 215b4f76236..5ef44268daa 100644 --- a/docs/c-runtime-library/reference/crtisvalidpointer.md +++ b/docs/c-runtime-library/reference/crtisvalidpointer.md @@ -37,27 +37,27 @@ Read/write accessibility to determine for the memory range. ## Return value -**_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. +**`_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 -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. +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 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: +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](/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). ## Requirements |Routine|Required header| |-------------|---------------------| -|**_CrtIsValidPointer**|\| +|**`_CrtIsValidPointer`**|\| -**_CrtIsValidPointer** is a Microsoft extension. For compatibility information, see [Compatibility](../compatibility.md). +**`_CrtIsValidPointer`** is a Microsoft extension. For compatibility information, see [Compatibility](../compatibility.md). ## Libraries diff --git a/docs/c-runtime-library/reference/crtmemcheckpoint.md b/docs/c-runtime-library/reference/crtmemcheckpoint.md index 8c9e770c911..de7a3d5ea88 100644 --- a/docs/c-runtime-library/reference/crtmemcheckpoint.md +++ b/docs/c-runtime-library/reference/crtmemcheckpoint.md @@ -12,7 +12,7 @@ ms.assetid: f1bacbaa-5a0c-498a-ac7a-b6131d83dfbc --- # `_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 @@ -25,23 +25,23 @@ void _CrtMemCheckpoint( ### Parameters *`state`*\ -Pointer to **_CrtMemState** structure to fill with the memory checkpoint. +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`](../debug.md) isn't 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](/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). -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. +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**|\, \| +|**`_CrtMemCheckpoint`**|\, \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtmemdifference.md b/docs/c-runtime-library/reference/crtmemdifference.md index ddcc8447a64..4f3dae34042 100644 --- a/docs/c-runtime-library/reference/crtmemdifference.md +++ b/docs/c-runtime-library/reference/crtmemdifference.md @@ -36,17 +36,17 @@ Pointer to a later memory state (**`_CrtMemState`** structure). ## Return value -If the difference in memory states is significant, **`_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`](../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 [`_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. +*`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 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). diff --git a/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md b/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md index ccbcced5258..094c743dcd1 100644 --- a/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md +++ b/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md @@ -25,17 +25,17 @@ void _CrtMemDumpAllObjectsSince( ### Parameters *`state`*\ -Pointer to the heap state to begin dumping from or **NULL**. +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`](../debug.md) isn't 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**) 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. +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](/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). ## Requirements @@ -51,7 +51,7 @@ 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 diff --git a/docs/c-runtime-library/reference/crtmemdumpstatistics.md b/docs/c-runtime-library/reference/crtmemdumpstatistics.md index 2c29ae38df6..8796e9b263f 100644 --- a/docs/c-runtime-library/reference/crtmemdumpstatistics.md +++ b/docs/c-runtime-library/reference/crtmemdumpstatistics.md @@ -29,17 +29,17 @@ 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`](../debug.md) isn't 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](../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). +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](/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). ## Requirements |Routine|Required header|Optional headers| |-------------|---------------------|----------------------| -|**_CrtMemDumpStatistics**|\|\| +|**`_CrtMemDumpStatistics`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtreportblocktype.md b/docs/c-runtime-library/reference/crtreportblocktype.md index ceabfb3c985..5d9d2b17f2a 100644 --- a/docs/c-runtime-library/reference/crtreportblocktype.md +++ b/docs/c-runtime-library/reference/crtreportblocktype.md @@ -29,11 +29,11 @@ Pointer to a valid debug heap block. ## 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). @@ -41,7 +41,7 @@ For information about the allocation block types and how they're used, see [Type |Routine|Required header| |-------------|---------------------| -|**_CrtReportBlockType**|\| +|**`_CrtReportBlockType`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetallochook.md b/docs/c-runtime-library/reference/crtsetallochook.md index a4eddb69bd7..aa33324d3d1 100644 --- a/docs/c-runtime-library/reference/crtsetallochook.md +++ b/docs/c-runtime-library/reference/crtsetallochook.md @@ -29,13 +29,13 @@ New client-defined allocation function to hook into the C run-time debug memory ## 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`](../debug.md) isn't 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,26 +43,26 @@ 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 hasn't 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. -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. +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**. 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](/visualstudio/debugger/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**|\| +|**`_CrtSetAllocHook`**|\| For more compatibility information, see [Compatibility](../compatibility.md). @@ -72,7 +72,7 @@ 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 diff --git a/docs/c-runtime-library/reference/crtsetbreakalloc.md b/docs/c-runtime-library/reference/crtsetbreakalloc.md index 6d9b75c99bc..554fabba8f9 100644 --- a/docs/c-runtime-library/reference/crtsetbreakalloc.md +++ b/docs/c-runtime-library/reference/crtsetbreakalloc.md @@ -33,17 +33,17 @@ 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`](../debug.md) isn't 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](/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). ## Requirements |Routine|Required header| |-------------|---------------------| -|**_CrtSetBreakAlloc**|\| +|**`_CrtSetBreakAlloc`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetdbgflag.md b/docs/c-runtime-library/reference/crtsetdbgflag.md index bbc381afc5d..d79683831e3 100644 --- a/docs/c-runtime-library/reference/crtsetdbgflag.md +++ b/docs/c-runtime-library/reference/crtsetdbgflag.md @@ -44,11 +44,11 @@ The following table lists the bit fields for **`_crtDbgFlag`** and describes the |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.| +|`_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** @@ -90,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). @@ -121,7 +121,7 @@ For an overview of memory management and the debug heap, see [CRT debug heap det 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](../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 diff --git a/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md b/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md index 3a2ef351d52..1e987bff958 100644 --- a/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md +++ b/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md @@ -31,9 +31,9 @@ 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 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**. +The default threshold is `SIZE_T_MAX`. Here's a list of the affected functions: @@ -89,7 +89,7 @@ Here's a list of the affected functions: |Routine|Required header| |-------------|---------------------| -|**_CrtSetDebugFillThreshold**|\| +|**`_CrtSetDebugFillThreshold`**|\| This function is Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetdumpclient.md b/docs/c-runtime-library/reference/crtsetdumpclient.md index 8a2ed17ea37..49b0c886ca7 100644 --- a/docs/c-runtime-library/reference/crtsetdumpclient.md +++ b/docs/c-runtime-library/reference/crtsetdumpclient.md @@ -12,7 +12,7 @@ ms.assetid: f3dd06d0-c331-4a12-b68d-25378d112033 --- # `_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 @@ -31,27 +31,27 @@ 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. 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 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](/visualstudio/debugger/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**|\| +|**`_CrtSetDumpClient`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetreportfile.md b/docs/c-runtime-library/reference/crtsetreportfile.md index 23190ad06d4..16b196eb5e4 100644 --- a/docs/c-runtime-library/reference/crtsetreportfile.md +++ b/docs/c-runtime-library/reference/crtsetreportfile.md @@ -12,7 +12,7 @@ ms.assetid: 3126537e-511b-44af-9c1c-0605265eabc4 --- # `_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 @@ -26,20 +26,20 @@ _HFILE _CrtSetReportFile( ### Parameters *`reportType`*\ -Report type: **_CRT_WARN**, **_CRT_ERROR**, and **_CRT_ASSERT**. +Report type: `_CRT_WARN`, `_CRT_ERROR`, and `_CRT_ASSERT`. *`reportFile`*\ New report file for *`reportType`*. ## 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](../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). +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 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. +**`_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 +57,9 @@ The following list shows the available choices for *`reportFile`* and the result 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,23 +69,23 @@ The following list shows the available choices for *`reportFile`* and the result _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. -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. +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**|\|\| +|**`_CrtSetReportFile`**|\|\| -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 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](../crt-library-features.md) only. diff --git a/docs/c-runtime-library/reference/crtsetreporthook.md b/docs/c-runtime-library/reference/crtsetreporthook.md index ea83d756e00..703207c7351 100644 --- a/docs/c-runtime-library/reference/crtsetreporthook.md +++ b/docs/c-runtime-library/reference/crtsetreporthook.md @@ -33,19 +33,19 @@ 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`](../debug.md) isn't 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). @@ -56,7 +56,7 @@ For more information about using other hook-capable run-time functions and writi |Routine|Required header| |-------------|---------------------| -|**_CrtSetReportHook**|\| +|**`_CrtSetReportHook`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md b/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md index 9a1d46d7d4e..28a3be8305c 100644 --- a/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md +++ b/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md @@ -30,22 +30,22 @@ int _CrtSetReportHookW2( ### Parameters *`mode`*\ -The action to take: **_CRT_RPTHOOK_INSTALL** or **_CRT_RPTHOOK_REMOVE**. +The action to take: `_CRT_RPTHOOK_INSTALL` or `_CRT_RPTHOOK_REMOVE`. *`pfnNewHook`*\ Report hook to install or remove in the narrow-character or wide-character version of this function. ## 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,7 +59,7 @@ 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](../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. @@ -68,8 +68,8 @@ These functions validate their parameters. If *`mode`* or *`pfnNewHook`* is inva |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_CrtSetReportHook2**|\|\| -|**_CrtSetReportHookW2**|\|\| +|**`_CrtSetReportHook2`**|\|\| +|**`_CrtSetReportHookW2`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetreportmode.md b/docs/c-runtime-library/reference/crtsetreportmode.md index aaf32682f49..a8b776ed8a1 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,14 +25,14 @@ 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 -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). +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 @@ -52,18 +52,18 @@ The following table lists the report types defined in `Crtdbg.h`. |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`**).| +|`_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`**| +|`_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'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`**: @@ -72,7 +72,7 @@ _CrtSetReportMode( _CRT_ASSERT, _CRTDBG_MODE_FILE | _CRTDBG_MODE_WNDW ); _CrtSetReportFile( _CRT_ASSERT, _CRTDBG_FILE_STDERR ); ``` -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. +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 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 5a068c1ed49..9fcc085593d 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 @@ -60,25 +60,25 @@ The number of fields that were successfully converted and assigned. The return v ## 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 doesn't 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](../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 -|TCHAR.H routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcscanf**|**_cscanf**|**_cscanf**|**_cwscanf**| -|**_tcscanf_l**|**_cscanf_l**|**_cscanf_l**|**_cwscanf_l**| +|`_tcscanf`|**`_cscanf`**|**`_cscanf`**|**`_cwscanf`**| +|`_tcscanf_l`|**`_cscanf_l`**|**`_cscanf_l`**|**`_cwscanf_l`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_cscanf**, **_cscanf_l**|\| -|**_cwscanf**, **_cwscanf_l**|\ or \| +|**`_cscanf`**, **`_cscanf_l`**|\| +|**`_cwscanf`**, **`_cwscanf_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 9ef2f3b82d1..3d7ba85a661 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 @@ -55,32 +55,32 @@ The locale to use. 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](../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 doesn't 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](../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 -|TCHAR.H routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \| +|**`_cscanf_s`**, **`_cscanf_s_l`**|\| +|**`_cwscanf_s`**, **`_cwscanf_s_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/csin-csinf-csinl.md b/docs/c-runtime-library/reference/csin-csinf-csinl.md index 60f4ca11bbc..3cb6875a979 100644 --- a/docs/c-runtime-library/reference/csin-csinf-csinl.md +++ b/docs/c-runtime-library/reference/csin-csinf-csinl.md @@ -45,13 +45,13 @@ 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**|\|\| +|**`csin`**, **`csinf`**, **`csinl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md b/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md index 50b81cb3c59..b150a97e06e 100644 --- a/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md +++ b/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md @@ -45,13 +45,13 @@ 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**|\|\| +|**`csinh`**, **`csinhf`**, **`csinhl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md b/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md index 0473eb39330..5f9d41c17b7 100644 --- a/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md +++ b/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md @@ -43,20 +43,20 @@ A complex number. The square root of *`z`*. The result is in the right half-plane. -|Input|SEH Exception|**_matherr** Exception| +|Input|SEH Exception|`_matherr` Exception| |-----------|-------------------|--------------------------| |± QNAN, IND|none|_DOMAIN| |- ∞|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**|\|\| +|**`csqrt`**, **`csqrtf`**, **`csqrtl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md b/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md index 5ae1f080de1..012ff41d889 100644 --- a/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md +++ b/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md @@ -43,20 +43,20 @@ A complex number that represents the angle, in radians. The tangent of *`z`*. -|Input|SEH Exception|**_matherr** Exception| +|Input|SEH Exception|`_matherr` Exception| |-----------|-------------------|--------------------------| |± ∞, QNAN, IND|none|_DOMAIN| -|± ∞ (**tan**, **tanf**)|INVALID|_DOMAIN| +|± ∞ (`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**|\|\| +|**`ctan`**, **`ctanf`**, **`ctanl`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md b/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md index 2d5dcb87f2c..5c625d3a34d 100644 --- a/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md +++ b/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md @@ -43,20 +43,20 @@ A complex number that represents an angle, in radians. The complex hyperbolic tangent of *`z`*. -|Input|SEH Exception|**_matherr** Exception| +|Input|SEH Exception|`_matherr` Exception| |-----------|-------------------|--------------------------| |± ∞, QNAN, IND|none|_DOMAIN| |± ∞ (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**|\|\| +|**`ctanh`**, **`ctanhf`**, **`ctanhl`**|\|\| For compatibility information, see [Compatibility](../compatibility.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 2e0c66075f4..c46cb84286c 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 @@ -32,19 +32,19 @@ Pointer to stored time to convert. ## Return value -A pointer to the character string result. **NULL** is returned when: +A pointer to the character string result. `NULL` is returned when: - *`sourceTime`* represents a date before midnight, January 1, 1970, UTC. -- 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. -- 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 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. +**`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`](../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: +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 @@ -54,32 +54,32 @@ A 24-hour clock is used. All fields have a constant width. The newline character 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](../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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tctime**|**ctime**|**ctime**|**_wctime**| -|**_tctime32**|**_ctime32**|**_ctime32**|**_wctime32**| -|**_tctime64**|**_ctime64**|**_ctime64**|**_wctime64**| +|`_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 \| +|**`ctime`**|\| +|**`_ctime32`**|\| +|**`_ctime64`**|\| +|**`_wctime`**|\ or \| +|**`_wctime32`**|\ or \| +|**`_wctime64`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 d237932d727..03fb6010995 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 @@ -75,15 +75,15 @@ errno_t _wctime64_s( ### Parameters *`buffer`*\ -Must be large enough to hold 26 characters. A pointer to the character string result, or **NULL** if: +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. -- 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`*\ The size of the buffer. @@ -99,15 +99,15 @@ Zero if successful. If there's a failure due to an invalid parameter, the invali |*`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| +|`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`](../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: +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` @@ -115,9 +115,9 @@ A 24-hour clock is used. All fields have a constant width. The new line characte 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`. This macro causes **`ctime_s`** to evaluate to **`_ctime32_s`**. We don't recommend it, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). @@ -127,18 +127,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| +|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**| +|`_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 \| +|**`ctime_s`**, **`_ctime32_s`**, **`_ctime64_s`**|\| +|**`_wctime_s`**, **`_wctime32_s`**, **`_wctime64_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/cwait.md b/docs/c-runtime-library/reference/cwait.md index 2684937c005..074c8b158aa 100644 --- a/docs/c-runtime-library/reference/cwait.md +++ b/docs/c-runtime-library/reference/cwait.md @@ -30,22 +30,22 @@ 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 -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.| +|`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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -53,7 +53,7 @@ For more information about these and other return codes, see [`errno, _doserrno, 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. diff --git a/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md b/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md index 2ae5b03badf..bfac04ee278 100644 --- a/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md +++ b/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md @@ -32,17 +32,17 @@ Beginning time. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -50,9 +50,9 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**difftime**|\| -|**_difftime32**|\| -|**_difftime64**|\| +|**`difftime`**|\| +|**`_difftime32`**|\| +|**`_difftime64`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/dup-dup2.md b/docs/c-runtime-library/reference/dup-dup2.md index 55549f51691..ef1b11c460a 100644 --- a/docs/c-runtime-library/reference/dup-dup2.md +++ b/docs/c-runtime-library/reference/dup-dup2.md @@ -30,7 +30,7 @@ Any file descriptor. ## 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. When passed an invalid file descriptor, the function also invokes the invalid parameter handler, as described in [Parameter validation](../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 return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.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 f6d609ee461..62b2320b294 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 @@ -47,40 +47,40 @@ Size of *`buffer`*. Environment variable name. *`blockType`*\ -Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +Requested type of the memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. *`filename`*\ -Pointer to the name of the source file or **NULL**. +Pointer to the name of the source file or `NULL`. *`lineNumber`*\ -Line number in source file or **NULL**. +Line number in source file or `NULL`. ## 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](../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 can't 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 don't need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_dupenv_s** and **_wdupenv_s** are remapped to **_dupenv_s_dbg** and **_wdupenv_s_dbg**, respectively, with the *`blockType`* set to **_NORMAL_BLOCK**. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information on block types, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_dupenv_s` and `_wdupenv_s` are remapped to **`_dupenv_s_dbg`** and **`_wdupenv_s_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information on block types, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tdupenv_s_dbg**|**_dupenv_s_dbg**|**_dupenv_s_dbg**|**_wdupenv_s_dbg**| +|`_tdupenv_s_dbg`|**`_dupenv_s_dbg`**|**`_dupenv_s_dbg`**|**`_wdupenv_s_dbg`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_dupenv_s_dbg**|\| -|**_wdupenv_s_dbg**|\| +|**`_dupenv_s_dbg`**|\| +|**`_wdupenv_s_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.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 02e6e3c623e..ffa7b6f4418 100644 --- a/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md +++ b/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md @@ -47,9 +47,9 @@ Environment variable name. 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](../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 can't 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 @@ -58,9 +58,9 @@ The **`_dupenv_s`** function searches the list of environment variables for *`va > [!NOTE] > It's the calling program's responsibility to free the memory by calling [`free`](free.md). -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 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 aren't 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`** 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`**. diff --git a/docs/c-runtime-library/reference/ecvt-s.md b/docs/c-runtime-library/reference/ecvt-s.md index db946a0381e..1505e9e4971 100644 --- a/docs/c-runtime-library/reference/ecvt-s.md +++ b/docs/c-runtime-library/reference/ecvt-s.md @@ -59,30 +59,30 @@ Sign of the converted number. 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). -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**. +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 |*`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.| +|`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 -**_ecvt_s** might generate an access violation if *`buffer`* doesn't point to valid memory and isn't **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. -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](../secure-template-overloads.md). @@ -94,7 +94,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_ecvt_s**|\|\| +|**`_ecvt_s`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ecvt.md b/docs/c-runtime-library/reference/ecvt.md index 885c0442113..4c81db89a48 100644 --- a/docs/c-runtime-library/reference/ecvt.md +++ b/docs/c-runtime-library/reference/ecvt.md @@ -41,21 +41,21 @@ Sign of the converted number. ## 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** won't 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. -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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -63,7 +63,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_ecvt**|\| +|**`_ecvt`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/endthread-endthreadex.md b/docs/c-runtime-library/reference/endthread-endthreadex.md index a2a40575a06..de299ec1698 100644 --- a/docs/c-runtime-library/reference/endthread-endthreadex.md +++ b/docs/c-runtime-library/reference/endthread-endthreadex.md @@ -32,11 +32,11 @@ 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. diff --git a/docs/c-runtime-library/reference/eof.md b/docs/c-runtime-library/reference/eof.md index 94c600a1cf7..a49fd4c5057 100644 --- a/docs/c-runtime-library/reference/eof.md +++ b/docs/c-runtime-library/reference/eof.md @@ -29,11 +29,11 @@ File descriptor referring to the open file. ## Return value -**_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. +**`_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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_eof**|\|\| +|**`_eof`**|\|\| For more compatibility information, see [Compatibility](../compatibility.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 5037a43eec2..30470f78310 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 @@ -58,17 +58,17 @@ A floating-point 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 **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`**. +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](../tgmath.md) for details. @@ -78,8 +78,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**erf**, **erff**, **erfl**, **erfc**, **erfcf**, **erfcl**|\| -|**erf** macro | \ | +|**`erf`**, **`erff`**, **`erfl`**, **`erfc`**, **`erfcf`**, **`erfcl`**|\| +|**`erf`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execl-wexecl.md b/docs/c-runtime-library/reference/execl-wexecl.md index 46019e3d52c..97c7eaf2fc1 100644 --- a/docs/c-runtime-library/reference/execl-wexecl.md +++ b/docs/c-runtime-library/reference/execl-wexecl.md @@ -44,30 +44,30 @@ List of pointers to the parameters. ## Return value -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. +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'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.| +|`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](../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 \|\| +|**`_execl`**|\|\| +|**`_wexecl`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execle-wexecle.md b/docs/c-runtime-library/reference/execle-wexecle.md index 4e01fd8583e..a9efce889df 100644 --- a/docs/c-runtime-library/reference/execle-wexecle.md +++ b/docs/c-runtime-library/reference/execle-wexecle.md @@ -49,17 +49,17 @@ Array of pointers to environment settings. ## Return value -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. +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| +|`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.| +|`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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -67,14 +67,14 @@ For more information about these return codes, see [`errno`, `_doserrno`, `_sys_ 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](../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 \|\| +|**`_execle`**|\|\| +|**`_wexecle`**|\ or \|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execlp-wexeclp.md b/docs/c-runtime-library/reference/execlp-wexeclp.md index 23619393bf9..b331ccda89d 100644 --- a/docs/c-runtime-library/reference/execlp-wexeclp.md +++ b/docs/c-runtime-library/reference/execlp-wexeclp.md @@ -44,32 +44,32 @@ List of pointers to parameters. ## Return value -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. +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| +|`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.| +|`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 [`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](../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 \|\| +|**`_execlp`**|\|\| +|**`_wexeclp`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execlpe-wexeclpe.md b/docs/c-runtime-library/reference/execlpe-wexeclpe.md index 3d4e9bb744e..f3e6a7c3b07 100644 --- a/docs/c-runtime-library/reference/execlpe-wexeclpe.md +++ b/docs/c-runtime-library/reference/execlpe-wexeclpe.md @@ -49,32 +49,32 @@ Array of pointers to environment settings. ## Return value -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. +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| +|`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.| +|`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 [`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](../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 \|\| +|**`_execlpe`**|\|\| +|**`_wexeclpe`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execv-wexecv.md b/docs/c-runtime-library/reference/execv-wexecv.md index 1c861908289..2f8139dc6cc 100644 --- a/docs/c-runtime-library/reference/execv-wexecv.md +++ b/docs/c-runtime-library/reference/execv-wexecv.md @@ -40,17 +40,17 @@ Array of pointers to parameters. ## Return value -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. +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| +|`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.| +|`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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -58,7 +58,7 @@ For more information about these and other return codes, see [`errno`, `_doserrn 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -66,8 +66,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_execv**|\|\| -|**_wexecv**|\ or \|\| +|**`_execv`**|\|\| +|**`_wexecv`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execve-wexecve.md b/docs/c-runtime-library/reference/execve-wexecve.md index eeacfd7bede..180bf560dab 100644 --- a/docs/c-runtime-library/reference/execve-wexecve.md +++ b/docs/c-runtime-library/reference/execve-wexecve.md @@ -45,17 +45,17 @@ Array of pointers to environment settings. ## Return value -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. +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| +|`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.| +|`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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -63,13 +63,13 @@ For more information about these and other return codes, see [`errno`, `_doserrn 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. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: +**`_execve`** and **`_wexecve`** validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: - *`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. +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). @@ -77,8 +77,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_execve**|\|\| -|**_wexecve**|\ or \|\| +|**`_execve`**|\|\| +|**`_wexecve`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execvp-wexecvp.md b/docs/c-runtime-library/reference/execvp-wexecvp.md index e3620b6da7b..094ec1bf80e 100644 --- a/docs/c-runtime-library/reference/execvp-wexecvp.md +++ b/docs/c-runtime-library/reference/execvp-wexecvp.md @@ -40,31 +40,31 @@ Array of pointers to parameters. ## Return value -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. +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| +|`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.| +|`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 [`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. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: +The **`_execvp`** functions validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: - *`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. +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). @@ -72,8 +72,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_execvp**|\|\| -|**_wexecvp**|\ or \|\| +|**`_execvp`**|\|\| +|**`_wexecvp`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/execvpe-wexecvpe.md b/docs/c-runtime-library/reference/execvpe-wexecvpe.md index 6d4ed2946bc..74123bcfc46 100644 --- a/docs/c-runtime-library/reference/execvpe-wexecvpe.md +++ b/docs/c-runtime-library/reference/execvpe-wexecvpe.md @@ -45,30 +45,30 @@ Array of pointers to environment settings. ## Return value -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. +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| +|`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.| +|`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`](../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. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: +The **`_execvpe`** functions validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: - *`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. +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). @@ -76,8 +76,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_execvpe**|\|\| -|**_wexecvpe**|\ or \|\| +|**`_execvpe`**|\|\| +|**`_wexecvpe`**|\ or \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/exit-exit-exit.md b/docs/c-runtime-library/reference/exit-exit-exit.md index 3e7cca266c7..8273a2da7f1 100644 --- a/docs/c-runtime-library/reference/exit-exit-exit.md +++ b/docs/c-runtime-library/reference/exit-exit-exit.md @@ -39,7 +39,7 @@ Exit status code. 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 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. +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. @@ -63,7 +63,7 @@ void last_fn() {} } ``` -Don't 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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md index 57dd4214a97..49f34864a55 100644 --- a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md +++ b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md @@ -61,7 +61,7 @@ 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](../tgmath.md) for details. @@ -71,8 +71,8 @@ By default, this function's global state is scoped to the application. To change |Routine|C header|C++ header| |-------------|--------------|------------------| -|**exp2**, **expf2**, **expl2**|\|\| -|**exp2** macro | \ || +|**`exp2`**, **`expf2`**, **`expl2`**|\|\| +|**`exp2`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/expand-dbg.md b/docs/c-runtime-library/reference/expand-dbg.md index 65138ecb9f8..721dd328d22 100644 --- a/docs/c-runtime-library/reference/expand-dbg.md +++ b/docs/c-runtime-library/reference/expand-dbg.md @@ -35,37 +35,37 @@ Pointer to the previously allocated memory block. Requested new size for the block (in bytes). *`blockType`*\ -Requested type for resized block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +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**. +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**. +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`](../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 -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). +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`](../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. +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 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. +**`_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 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. +When *`newSize`* is greater than the original block size, the memory block is expanded. During an expansion, if the memory block can't be expanded to accommodate the requested size, `NULL` is returned. When *`newSize`* is less than the original block size, the memory block is contracted until the new size is obtained. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). -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**. +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**|\| +|**`_expand_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/expand.md b/docs/c-runtime-library/reference/expand.md index 114ef5efe49..e6afe387b1a 100644 --- a/docs/c-runtime-library/reference/expand.md +++ b/docs/c-runtime-library/reference/expand.md @@ -33,24 +33,24 @@ New size in bytes. ## 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 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 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). +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 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`* shouldn't 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](/visualstudio/debugger/crt-debug-heap-details). -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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -58,7 +58,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_expand**|\| +|**`_expand`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md b/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md index eb21ef37477..db23e19fd9c 100644 --- a/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md +++ b/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md @@ -42,11 +42,11 @@ The floating-point exponential 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`](../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](../tgmath.md) for details. @@ -54,8 +54,8 @@ If you use the \ `expm1()` macro, the type of the argument determines |Routine|Required header| |-------------|---------------------| -|**expm1**, **expm1f**, **expm1l**|\| -|**expm1** macro | \ | +|**`expm1`**, **`expm1f`**, **`expm1l`**|\| +|**`expm1`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fclose-fcloseall.md b/docs/c-runtime-library/reference/fclose-fcloseall.md index 5bef68d304d..7a001b4244a 100644 --- a/docs/c-runtime-library/reference/fclose-fcloseall.md +++ b/docs/c-runtime-library/reference/fclose-fcloseall.md @@ -25,22 +25,22 @@ int _fcloseall( void ); ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## 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](../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. +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. 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 `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. +> 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`**. diff --git a/docs/c-runtime-library/reference/fclose-nolock.md b/docs/c-runtime-library/reference/fclose-nolock.md index 8b721d3cd19..2290f33123a 100644 --- a/docs/c-runtime-library/reference/fclose-nolock.md +++ b/docs/c-runtime-library/reference/fclose-nolock.md @@ -25,15 +25,15 @@ int _fclose_nolock( ### Parameters *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## 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 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. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fclose_nolock**|\| +|**`_fclose_nolock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fcvt-s.md b/docs/c-runtime-library/reference/fcvt-s.md index 75be88e6d90..55986a3b612 100644 --- a/docs/c-runtime-library/reference/fcvt-s.md +++ b/docs/c-runtime-library/reference/fcvt-s.md @@ -59,30 +59,30 @@ Pointer to the stored sign indicator. 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). -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**. +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 |*`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.| +|`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`* doesn't point to valid memory and isn't **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. -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](../secure-template-overloads.md). @@ -94,7 +94,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_fcvt_s**|\|\| +|**`_fcvt_s`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fcvt.md b/docs/c-runtime-library/reference/fcvt.md index 4f84d27dcf6..f7b66bcec5b 100644 --- a/docs/c-runtime-library/reference/fcvt.md +++ b/docs/c-runtime-library/reference/fcvt.md @@ -41,21 +41,21 @@ Pointer to the stored sign indicator. ## 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** won't 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. -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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -63,7 +63,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fcvt**|\| +|**`_fcvt`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md index 33c6f84a0c2..7e70a7d1eae 100644 --- a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md +++ b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md @@ -74,7 +74,7 @@ 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](../tgmath.md) for details. @@ -84,8 +84,8 @@ Except for the NaN handling, this function is equivalent to `fmax(x - y, 0)`. |Function|C header|C++ header| |--------------|--------------|------------------| -|**fdim**, **fdimf**, **fdiml**|\|\| -|**fdim** macro | \ || +|**`fdim`**, **`fdimf`**, **`fdiml`**|\|\| +|**`fdim`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/feclearexcept1.md b/docs/c-runtime-library/reference/feclearexcept1.md index e342468c457..c56fd431ee1 100644 --- a/docs/c-runtime-library/reference/feclearexcept1.md +++ b/docs/c-runtime-library/reference/feclearexcept1.md @@ -33,16 +33,16 @@ Returns zero if *`excepts`* is zero, or if all the specified exceptions were suc ## 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.| +|`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. @@ -50,7 +50,7 @@ The *`excepts`* argument may be zero, or the bitwise OR of one or more of the su |Function|C header|C++ header| |--------------|--------------|------------------| -|**feclearexcept**|\|\| +|**`feclearexcept`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fegetenv1.md b/docs/c-runtime-library/reference/fegetenv1.md index 0bcf96440f1..d45abb89faf 100644 --- a/docs/c-runtime-library/reference/fegetenv1.md +++ b/docs/c-runtime-library/reference/fegetenv1.md @@ -25,7 +25,7 @@ int fegetenv( ### Parameters *`penv`*\ -Pointer to an **fenv_t** object to contain the current floating-point environment values. +Pointer to an `fenv_t` object to contain the current floating-point environment values. ## Return value @@ -33,7 +33,7 @@ Returns 0 if the floating-point environment was successfully stored in *`penv`*. ## 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 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. +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). @@ -41,7 +41,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**fegetenv**|\|\| +|**`fegetenv`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fegetexceptflag2.md b/docs/c-runtime-library/reference/fegetexceptflag2.md index 019dbc457aa..02db100dc3a 100644 --- a/docs/c-runtime-library/reference/fegetexceptflag2.md +++ b/docs/c-runtime-library/reference/fegetexceptflag2.md @@ -26,7 +26,7 @@ int fegetexceptflag( ### Parameters *`pstatus`*\ -A pointer to a **fexcept_t** object to contain the current values of the exception flags specified by *`excepts`*. +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`*. @@ -37,16 +37,16 @@ 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.| +|`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. @@ -56,7 +56,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**fegetexceptflag**|\|\| +|**`fegetexceptflag`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fegetround-fesetround2.md b/docs/c-runtime-library/reference/fegetround-fesetround2.md index a262961b643..d37757c2e86 100644 --- a/docs/c-runtime-library/reference/fegetround-fesetround2.md +++ b/docs/c-runtime-library/reference/fegetround-fesetround2.md @@ -31,9 +31,9 @@ The rounding mode to set, as one of the floating-point rounding macros. If the v ## 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 @@ -41,12 +41,12 @@ Floating-point operations can use one of several rounding modes. These modes con |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.| +|`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: @@ -54,13 +54,13 @@ The current rounding mode affects these operations: - 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 doesn't affect these operations: -- The **trunc**, **ceil**, **floor**, and **lround** library functions. +- The `trunc`, `ceil`, `floor`, and `lround` library functions. - Floating-point to integer implicit casts and conversions, which always round towards zero. @@ -72,7 +72,7 @@ To use these functions, you must turn off floating-point optimizations that coul |Function|C header|C++ header| |--------------|--------------|------------------| -|**fegetround**, **fesetround**|\|\| +|**`fegetround`**, **`fesetround`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/feholdexcept2.md b/docs/c-runtime-library/reference/feholdexcept2.md index df6456be16e..700f550f79f 100644 --- a/docs/c-runtime-library/reference/feholdexcept2.md +++ b/docs/c-runtime-library/reference/feholdexcept2.md @@ -25,7 +25,7 @@ int feholdexcept( ### Parameters *`penv`*\ -Pointer to an **fenv_t** object to contain a copy of the floating-point environment. +Pointer to an `fenv_t` object to contain a copy of the floating-point environment. ## Return value @@ -33,9 +33,9 @@ Returns zero if and only if the function is able to successfully turn on non-sto ## 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 mode 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 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). @@ -43,7 +43,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**feholdexcept**|\|\| +|**`feholdexcept`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/feof.md b/docs/c-runtime-library/reference/feof.md index edcf6602105..a4f97756a32 100644 --- a/docs/c-runtime-library/reference/feof.md +++ b/docs/c-runtime-library/reference/feof.md @@ -25,19 +25,19 @@ int feof( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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](../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. 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 haven't 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 behavior, see [Global state in the CRT](../global-state.md). @@ -45,7 +45,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**feof**|\| +|**`feof`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/feraiseexcept.md b/docs/c-runtime-library/reference/feraiseexcept.md index 7fa417d5fd9..3ad83b7f653 100644 --- a/docs/c-runtime-library/reference/feraiseexcept.md +++ b/docs/c-runtime-library/reference/feraiseexcept.md @@ -32,22 +32,22 @@ 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.| +|`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). -**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 diff --git a/docs/c-runtime-library/reference/ferror.md b/docs/c-runtime-library/reference/ferror.md index 2dd29e1fcd9..b340bb3fc92 100644 --- a/docs/c-runtime-library/reference/ferror.md +++ b/docs/c-runtime-library/reference/ferror.md @@ -25,17 +25,17 @@ int ferror( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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](../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. 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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**ferror**|\| +|**`ferror`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fesetenv1.md b/docs/c-runtime-library/reference/fesetenv1.md index da56a0fcd45..b2fa358d81e 100644 --- a/docs/c-runtime-library/reference/fesetenv1.md +++ b/docs/c-runtime-library/reference/fesetenv1.md @@ -25,7 +25,7 @@ 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. +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 @@ -33,7 +33,7 @@ Returns 0 if the environment was successfully set. Otherwise, it returns a nonze ## 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. 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. +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 doesn't raise those exceptions. @@ -43,7 +43,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**fesetenv**|\|\| +|**`fesetenv`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fesetexceptflag2.md b/docs/c-runtime-library/reference/fesetexceptflag2.md index d3231c50fd1..37bfe491c7b 100644 --- a/docs/c-runtime-library/reference/fesetexceptflag2.md +++ b/docs/c-runtime-library/reference/fesetexceptflag2.md @@ -26,7 +26,7 @@ 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). +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`*\ The floating-point exception status flags to set. @@ -37,16 +37,16 @@ If all the specified exception status flags are set successfully, returns 0. Oth ## 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 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 \: +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.| +|`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. @@ -56,7 +56,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**fesetexceptflag**|\|\| +|**`fesetexceptflag`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fetestexcept1.md b/docs/c-runtime-library/reference/fetestexcept1.md index ee4b70b4f22..da143255021 100644 --- a/docs/c-runtime-library/reference/fetestexcept1.md +++ b/docs/c-runtime-library/reference/fetestexcept1.md @@ -33,16 +33,16 @@ On success, returns a bitmask containing a bitwise OR of the floating-point exce ## 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.| +|`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. @@ -52,7 +52,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**fetestexcept**|\|\| +|**`fetestexcept`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/feupdateenv.md b/docs/c-runtime-library/reference/feupdateenv.md index a5eade0ed9e..d75e0b057ce 100644 --- a/docs/c-runtime-library/reference/feupdateenv.md +++ b/docs/c-runtime-library/reference/feupdateenv.md @@ -24,7 +24,7 @@ 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. +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 @@ -32,7 +32,7 @@ Returns 0 if all actions completed successfully. Otherwise, it returns a nonzero ## 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`* 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. +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). @@ -40,7 +40,7 @@ To use this function, you must turn off floating-point optimizations that could |Function|C header|C++ header| |--------------|--------------|------------------| -|**feupdateenv**|\|\| +|**`feupdateenv`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fflush-nolock.md b/docs/c-runtime-library/reference/fflush-nolock.md index 3439d34ef26..449c36279aa 100644 --- a/docs/c-runtime-library/reference/fflush-nolock.md +++ b/docs/c-runtime-library/reference/fflush-nolock.md @@ -25,7 +25,7 @@ int _fflush_nolock( ### Parameters *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## Return value @@ -33,7 +33,7 @@ See [`fflush`](fflush.md). ## Remarks -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. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fflush_nolock**|\| +|**`_fflush_nolock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fflush.md b/docs/c-runtime-library/reference/fflush.md index ba9c646e7a7..496df3316b4 100644 --- a/docs/c-runtime-library/reference/fflush.md +++ b/docs/c-runtime-library/reference/fflush.md @@ -24,20 +24,20 @@ int fflush( ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## 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, **`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`. diff --git a/docs/c-runtime-library/reference/fgetc-fgetwc.md b/docs/c-runtime-library/reference/fgetc-fgetwc.md index c1d60ca09d3..167546f68a5 100644 --- a/docs/c-runtime-library/reference/fgetc-fgetwc.md +++ b/docs/c-runtime-library/reference/fgetc-fgetwc.md @@ -28,21 +28,21 @@ wint_t fgetwc( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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`](../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**. +**`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. -**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 when *`stream`* is opened in text mode or binary mode, respectively. +**`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 aren't 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](../unicode-stream-i-o-in-text-and-binary-modes.md). @@ -50,16 +50,16 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_fgettc**|**fgetc**|**fgetc**|**fgetwc**| +|`_fgettc`|**`fgetc`**|**`fgetc`**|**`fgetwc`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**fgetc**|\| -|**fgetwc**|\ or \| +|**`fgetc`**|\| +|**`fgetwc`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 3b81cbfcb19..da391a38201 100644 --- a/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md +++ b/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md @@ -28,7 +28,7 @@ wint_t _fgetwc_nolock( ### Parameters *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## Return value @@ -36,22 +36,22 @@ See[`fgetc`, `fgetwc`](fgetc-fgetwc.md). ## Remarks -**_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. +**`_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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_fgettc_nolock**|**_fgetc_nolock**|**_fgetc_nolock**|**_fgetwc_nolock**| +|**`_fgettc_nolock`**|**`_fgetc_nolock`**|**`_fgetc_nolock`**|**`_fgetwc_nolock`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**_fgetc_nolock**|\| -|**_fgetwc_nolock**|\ or \| +|**`_fgetc_nolock`**|\| +|**`_fgetwc_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fgetchar-fgetwchar.md b/docs/c-runtime-library/reference/fgetchar-fgetwchar.md index 6b730427002..4d27447758d 100644 --- a/docs/c-runtime-library/reference/fgetchar-fgetwchar.md +++ b/docs/c-runtime-library/reference/fgetchar-fgetwchar.md @@ -12,7 +12,7 @@ ms.assetid: 8bce874c-701a-41a3-b1b2-feff266fb5b9 --- # `_fgetchar`, `_fgetwchar` -Reads a character from **stdin**. +Reads a character from `stdin`. ## Syntax @@ -23,13 +23,13 @@ wint_t _fgetwchar( void ); ## 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`](../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'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**. +**`_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 aren't compatible with the ANSI standard. @@ -37,18 +37,18 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_fgettchar**|**_fgetchar**|**_fgetchar**|**_fgetwchar**| +|`_fgettchar`|**`_fgetchar`**|**`_fgetchar`**|**`_fgetwchar`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**_fgetchar**|\| -|**_fgetwchar**|\ or \| +|**`_fgetchar`**|\| +|**`_fgetwchar`**|\ 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](../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 diff --git a/docs/c-runtime-library/reference/fgetpos.md b/docs/c-runtime-library/reference/fgetpos.md index 1a112cb8020..fbc962de825 100644 --- a/docs/c-runtime-library/reference/fgetpos.md +++ b/docs/c-runtime-library/reference/fgetpos.md @@ -33,11 +33,11 @@ Position-indicator storage. ## 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 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). +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 behavior, see [Global state in the CRT](../global-state.md). @@ -45,7 +45,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**fgetpos**|\| +|**`fgetpos`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fgets-fgetws.md b/docs/c-runtime-library/reference/fgets-fgetws.md index 87daf997102..de57b94a507 100644 --- a/docs/c-runtime-library/reference/fgets-fgetws.md +++ b/docs/c-runtime-library/reference/fgets-fgetws.md @@ -38,11 +38,11 @@ Storage location for data. Maximum number of characters to read. *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## 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](../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`. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/filelength-filelengthi64.md b/docs/c-runtime-library/reference/filelength-filelengthi64.md index b157e32d1b7..3003c87eaa4 100644 --- a/docs/c-runtime-library/reference/filelength-filelengthi64.md +++ b/docs/c-runtime-library/reference/filelength-filelengthi64.md @@ -32,7 +32,7 @@ Target the file descriptor. ## 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](../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 @@ -42,8 +42,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_filelength**|\| -|**_filelengthi64**|\| +|**`_filelength`**|\| +|**`_filelengthi64`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fileno.md b/docs/c-runtime-library/reference/fileno.md index 49aaf770bb4..b2be83c2103 100644 --- a/docs/c-runtime-library/reference/fileno.md +++ b/docs/c-runtime-library/reference/fileno.md @@ -24,11 +24,11 @@ int _fileno( ### Parameters *`stream`*\ -Pointer to the **`FILE`** structure. +Pointer to the `FILE` structure. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/findclose.md b/docs/c-runtime-library/reference/findclose.md index 9c7b6790f51..cb65562c22c 100644 --- a/docs/c-runtime-library/reference/findclose.md +++ b/docs/c-runtime-library/reference/findclose.md @@ -25,11 +25,11 @@ int _findclose( ### Parameters *`handle`*\ -The search handle returned by a previous call to **_findfirst**. +The search handle returned by a previous call to `_findfirst`. ## 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 @@ -39,7 +39,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_findclose**|\| +|**`_findclose`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/findfirst-functions.md b/docs/c-runtime-library/reference/findfirst-functions.md index 37978c876a9..b43d557feb5 100644 --- a/docs/c-runtime-library/reference/findfirst-functions.md +++ b/docs/c-runtime-library/reference/findfirst-functions.md @@ -77,14 +77,14 @@ File information buffer. ## 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 couldn't 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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -102,13 +102,13 @@ These functions use various forms of the **`_finddata_t`** structure for the *`f The variations that use a 64-bit time type enable file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC. The ones that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findfirst`** or **`_wfindfirst`** or, if you need to support file sizes larger than 3 GB, use **`_findfirsti64`** or **`_wfindfirsti64`**. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this change is a breaking change for an application, you might define **`_USE_32BIT_TIME_T`** to revert to the old behavior. If **`_USE_32BIT_TIME_T`** is defined, **`_findfirst`**, **`_finfirsti64`**, and their corresponding Unicode versions use a 32-bit time. +Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findfirst`** or **`_wfindfirst`** or, if you need to support file sizes larger than 3 GB, use **`_findfirsti64`** or **`_wfindfirsti64`**. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this change is a breaking change for an application, you might define `_USE_32BIT_TIME_T` to revert to the old behavior. If `_USE_32BIT_TIME_T` is defined, **`_findfirst`**, **`_finfirsti64`**, and their corresponding Unicode versions use a 32-bit time. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Time Type and File Length Type Variations of _findfirst -|Functions|**`_USE_32BIT_TIME_T`** defined?|Time type|File length type| +|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| diff --git a/docs/c-runtime-library/reference/findnext-functions.md b/docs/c-runtime-library/reference/findnext-functions.md index f9cfb932dc7..35e0ead5c82 100644 --- a/docs/c-runtime-library/reference/findnext-functions.md +++ b/docs/c-runtime-library/reference/findnext-functions.md @@ -70,75 +70,75 @@ int _wfindnext64i32( ### Parameters *`handle`*\ -The search handle returned by a previous call to **_findfirst**. +The search handle returned by a previous call to `_findfirst`. *`fileinfo`*\ File information buffer. ## 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**. | +| `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](../parameter-validation.md). ## Remarks -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. +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'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 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**, **_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 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| +|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| +|**`_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| +|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**| +|`_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 \| +|**`_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). diff --git a/docs/c-runtime-library/reference/floating-point-ordering.md b/docs/c-runtime-library/reference/floating-point-ordering.md index 5b40d6aa51c..987142c2e8d 100644 --- a/docs/c-runtime-library/reference/floating-point-ordering.md +++ b/docs/c-runtime-library/reference/floating-point-ordering.md @@ -90,11 +90,11 @@ The floating-point values to compare. 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`* 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 **`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 @@ -104,7 +104,7 @@ These comparison operations are implemented as macros when compiled as C, and as |Function|Required header (C)|Required header (C++)| |--------------|---------------------------|-------------------------------| -| **isgreater**, **isgreaterequal**, **isless**,
**islessequal**, **islessgreater**, **isunordered** | \ | \ or \ | +| **`isgreater`**, **`isgreaterequal`**, **`isless`**,
**`islessequal`**, **`islessgreater`**, **`isunordered`** | \ | \ or \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/floating-point-primitives.md b/docs/c-runtime-library/reference/floating-point-primitives.md index d150f2c813e..14f1346eed9 100644 --- a/docs/c-runtime-library/reference/floating-point-primitives.md +++ b/docs/c-runtime-library/reference/floating-point-primitives.md @@ -36,11 +36,11 @@ These floating-point primitives implement the C versions of the CRT macro [`fpcl |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 | +| `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 more detail, you can use the Microsoft-specific [`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) functions. Use the [`fpclassify`](fpclassify.md) macro or function for portability. @@ -84,9 +84,9 @@ These floating-point primitives take two arguments, *`x`* and *`y`*, and return | 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. @@ -111,11 +111,11 @@ These floating-point primitives implement the C++ versions of the CRT function [ |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 | +| `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 more detail, you can use the Microsoft-specific [`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) functions. Use the [`fpclassify`](fpclassify.md) function for portability. @@ -139,7 +139,7 @@ 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 @@ -161,7 +161,7 @@ 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`, `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 @@ -183,7 +183,7 @@ 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 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. +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 @@ -208,7 +208,7 @@ 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`* * 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. +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 @@ -226,7 +226,7 @@ Pointer to the bitwise representation of a floating-point value expressed as an ### 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 diff --git a/docs/c-runtime-library/reference/floor-floorf-floorl.md b/docs/c-runtime-library/reference/floor-floorf-floorl.md index c7828849e4c..96eb5828674 100644 --- a/docs/c-runtime-library/reference/floor-floorf-floorl.md +++ b/docs/c-runtime-library/reference/floor-floorf-floorl.md @@ -42,17 +42,17 @@ Floating-point 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| +|± 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](../tgmath.md) for details. @@ -62,8 +62,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**floor**, **floorf**, **floorl**|\| -|**floor** macro | \ | +|**`floor`**, **`floorf`**, **`floorl`**|\| +|**`floor`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/flushall.md b/docs/c-runtime-library/reference/flushall.md index 8b21b327850..56de2b77e25 100644 --- a/docs/c-runtime-library/reference/flushall.md +++ b/docs/c-runtime-library/reference/flushall.md @@ -22,15 +22,15 @@ int _flushall( void ); ## 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](../stream-i-o.md), [`fopen`](fopen-wfopen.md), and [`_fdopen`](fdopen-wfdopen.md). @@ -40,7 +40,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_flushall**|\| +|**`_flushall`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fma-fmaf-fmal.md b/docs/c-runtime-library/reference/fma-fmaf-fmal.md index 5f12b66d721..4fd8f10e9e3 100644 --- a/docs/c-runtime-library/reference/fma-fmaf-fmal.md +++ b/docs/c-runtime-library/reference/fma-fmaf-fmal.md @@ -80,7 +80,7 @@ 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](../tgmath.md) for details. @@ -92,8 +92,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**fma**, **fmaf**, **fmal**|\|\| -|**fma** macro | \ || +|**`fma`**, **`fmaf`**, **`fmal`**|\|\| +|**`fma`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md b/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md index 8b43f4ef4f1..6452a943a55 100644 --- a/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md +++ b/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md @@ -77,8 +77,8 @@ If you use the \ `fmax()` macro, the type of the argument determines w |Function|C header|C++ header| |--------------|--------------|------------------| -|**fmax**, **fmaxf**, **fmaxl**|\|\ or \| -|**fmax** macro | \ || +|**`fmax`**, **`fmaxf`**, **`fmaxl`**|\|\ or \| +|**`fmax`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fmin-fminf-fminl.md b/docs/c-runtime-library/reference/fmin-fminf-fminl.md index 31ab05b801a..18350cb627b 100644 --- a/docs/c-runtime-library/reference/fmin-fminf-fminl.md +++ b/docs/c-runtime-library/reference/fmin-fminf-fminl.md @@ -63,11 +63,11 @@ If successful, returns the smaller of *`x`* or *`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 does not 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](../tgmath.md) for details. @@ -75,8 +75,8 @@ If you use the \ `fmin()` macro, the type of the argument determines w |Routine|Required header| |-------------|---------------------| -|**fmin**, **fminf**, **fminl**|C: \
C++: \ or \| -|**fmin** macro | \ | +|**`fmin`**, **`fminf`**, **`fminl`**|C: \
C++: \ or \| +|**`fmin`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.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 c2053360f79..dda5eb708ec 100644 --- a/docs/c-runtime-library/reference/fopen-s-wfopen-s.md +++ b/docs/c-runtime-library/reference/fopen-s-wfopen-s.md @@ -47,13 +47,13 @@ Zero if successful; an error code on failure. For more information about these e | *`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. @@ -61,7 +61,7 @@ The **`fopen_s`** function opens the file that's specified by *`filename`*. **`_ 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`](../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,7 +105,7 @@ 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. @@ -118,11 +118,11 @@ In addition to the values above, the following characters can be included in *`m | **`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, **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. 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. 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`](../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](../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). diff --git a/docs/c-runtime-library/reference/fopen-wfopen.md b/docs/c-runtime-library/reference/fopen-wfopen.md index 96d6a1fa494..eadd5d9534a 100644 --- a/docs/c-runtime-library/reference/fopen-wfopen.md +++ b/docs/c-runtime-library/reference/fopen-wfopen.md @@ -37,7 +37,7 @@ 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](../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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -47,7 +47,7 @@ The **`fopen`** function opens the file that is specified by *`filename`*. By de **`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. -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). +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,7 +57,7 @@ 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](../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. @@ -72,7 +72,7 @@ The following table summarizes the modes that are used for various **`ccs`** fla | 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`** | @@ -99,7 +99,7 @@ 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. @@ -110,11 +110,11 @@ In addition to the earlier values, the following characters can be appended to * | **`t`** | Open in text (translated) mode. | | **`b`** | Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. | -In text mode, **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`](../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](../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). @@ -130,7 +130,7 @@ The following options can be appended to *`mode`* to specify more behaviors. | **`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. | +| **`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. | 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. diff --git a/docs/c-runtime-library/reference/fpclass-fpclassf.md b/docs/c-runtime-library/reference/fpclass-fpclassf.md index 6211f12e609..1f3653fff5a 100644 --- a/docs/c-runtime-library/reference/fpclass-fpclassf.md +++ b/docs/c-runtime-library/reference/fpclass-fpclassf.md @@ -36,16 +36,16 @@ The **`_fpclass`** and **`_fpclassf`** functions return an integer value that 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`)| +|`_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 diff --git a/docs/c-runtime-library/reference/fpclassify.md b/docs/c-runtime-library/reference/fpclassify.md index 8cdabd1ba7e..b43761c408f 100644 --- a/docs/c-runtime-library/reference/fpclassify.md +++ b/docs/c-runtime-library/reference/fpclassify.md @@ -40,27 +40,27 @@ The floating-point value to test. ## 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| +|`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 \| +|**`fpclassify`**|\|\ or \| -The **fpclassify** macro and **fpclassify** functions conform to the ISO C99 and C++11 specifications. For more compatibility information, see [Compatibility](../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 diff --git a/docs/c-runtime-library/reference/fpieee-flt.md b/docs/c-runtime-library/reference/fpieee-flt.md index fcdd5fa0dc6..868ed18be1d 100644 --- a/docs/c-runtime-library/reference/fpieee-flt.md +++ b/docs/c-runtime-library/reference/fpieee-flt.md @@ -37,28 +37,28 @@ Pointer to the user's IEEE trap-handler routine. ## 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**.| +|`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`.| -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. 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. ## Requirements |Function|Required header| |--------------|---------------------| -|**_fpieee_flt**|\| +|**`_fpieee_flt`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fpreset.md b/docs/c-runtime-library/reference/fpreset.md index c87795234bd..b2d23b4ae3d 100644 --- a/docs/c-runtime-library/reference/fpreset.md +++ b/docs/c-runtime-library/reference/fpreset.md @@ -22,7 +22,7 @@ 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 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`. 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. @@ -30,7 +30,7 @@ This function is deprecated when compiling with [/clr (Common Language Runtime C |Function|Required header| |--------------|---------------------| -|**_fpreset**|\| +|**`_fpreset`**|\| For more compatibility information, see [Compatibility](../compatibility.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 75976d80ad5..cbc580a1f14 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 @@ -43,7 +43,7 @@ int _fwprintf_l( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`format`*\ Format-control string. @@ -56,7 +56,7 @@ The locale to use. ## 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](../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`**. +**`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`**. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.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 0014156e4c8..f5ea87ffcd9 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 @@ -43,7 +43,7 @@ int _fwprintf_p_l( ### Parameters *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. *`format`*\ Format-control string. @@ -56,29 +56,29 @@ The locale to use. ## 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](../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 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](../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. > > 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](../parameter-validation.md), if either *`stream`* or *`format`* is a null pointer or if there are any unknown or badly formed formatting specifiers. If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_ftprintf_p`|**`_fprintf_p`**|**`_fprintf_p`**|**`_fwprintf_p`**| +|`_ftprintf_p_l`|**`_fprintf_p_l`**|**`_fprintf_p_l`**|**`_fwprintf_p_l`**| For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). @@ -86,8 +86,8 @@ For more information, see [Format specification syntax](../format-specification- |Function|Required header| |--------------|---------------------| -|**_fprintf_p**, **_fprintf_p_l**|\| -|**_fwprintf_p**, **_fwprintf_p_l**|\ or \| +|**`_fprintf_p`**, **`_fprintf_p_l`**|\| +|**`_fwprintf_p`**, **`_fwprintf_p_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md b/docs/c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md index d375b3ca3a8..9c9b3b4764e 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 @@ -43,7 +43,7 @@ int _fwprintf_s_l( ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. *`format`*\ Format-control string. @@ -72,11 +72,11 @@ The versions of these functions with the **`_l`** suffix are identical except th > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -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](../parameter-validation.md), if either *`stream`* or *`format`* is a `NULL` pointer. The format string itself is also validated. If there are any unknown or badly formed formatting specifiers, these functions generate the invalid parameter exception. In all cases, If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| +|`TCHAR.H` routine|`_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`**| diff --git a/docs/c-runtime-library/reference/fputc-fputwc.md b/docs/c-runtime-library/reference/fputc-fputwc.md index d370388f798..01a029d6192 100644 --- a/docs/c-runtime-library/reference/fputc-fputwc.md +++ b/docs/c-runtime-library/reference/fputc-fputwc.md @@ -33,45 +33,45 @@ wint_t fputwc( Character to be written. *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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](../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`. 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. 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. +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** doesn't 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 aren't 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 when *`stream`* is opened in text mode or binary mode, respectively.| +|**`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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_fputtc**|**fputc**|**fputc**|**fputwc**| +|`_fputtc`|**`fputc`**|**`fputc`**|**`fputwc`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**fputc**|\| -|**fputwc**|\ or \| +|**`fputc`**|\| +|**`fputwc`**|\ 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](../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 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 db8d66f89e7..f5aac82111f 100644 --- a/docs/c-runtime-library/reference/fputc-nolock-fputwc-nolock.md +++ b/docs/c-runtime-library/reference/fputc-nolock-fputwc-nolock.md @@ -33,7 +33,7 @@ wint_t _fputwc_nolock( Character to be written. *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## Return value @@ -41,26 +41,26 @@ Each of these functions returns the character written. For error information, se ## 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 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. -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`** does not currently support output into a UNICODE stream. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_fputtc_nolock**|**_fputc_nolock**|**_fputc_nolock**|**_fputwc_nolock**| +|`_fputtc_nolock`|**`_fputc_nolock`**|**`_fputc_nolock`**|**`_fputwc_nolock`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**_fputc_nolock**|\| -|**_fputwc_nolock**|\ or \| +|**`_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](../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 more compatibility information, see [Compatibility](../compatibility.md). ## Example diff --git a/docs/c-runtime-library/reference/fputchar-fputwchar.md b/docs/c-runtime-library/reference/fputchar-fputwchar.md index 2f3f9ddf50d..f42cfb4f72f 100644 --- a/docs/c-runtime-library/reference/fputchar-fputwchar.md +++ b/docs/c-runtime-library/reference/fputchar-fputwchar.md @@ -12,7 +12,7 @@ ms.assetid: b92ff600-a924-4f2b-b0e7-3097ee31bdff --- # `_fputchar`, `_fputwchar` -Writes a character to **stdout**. +Writes a character to `stdout`. ## Syntax @@ -32,30 +32,30 @@ Character to be written. ## 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](../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, they return `EOF` (or `WEOF`) and set `errno` to `EINVAL`. 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_fputtchar**|**_fputchar**|**_fputchar**|**_fputwchar**| +|`_fputtchar`|**`_fputchar`**|**`_fputchar`**|**`_fputwchar`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**_fputchar**|\| -|**_fputwchar**|\ or \| +|**`_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](../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 more compatibility information, see [Compatibility](../compatibility.md). ## Example diff --git a/docs/c-runtime-library/reference/fputs-fputws.md b/docs/c-runtime-library/reference/fputs-fputws.md index 68d258b367b..e4516d816fa 100644 --- a/docs/c-runtime-library/reference/fputs-fputws.md +++ b/docs/c-runtime-library/reference/fputs-fputws.md @@ -32,11 +32,11 @@ 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](../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 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -50,7 +50,7 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_fputts`**|**`fputs`**|**`fputs`**|**`fputws`**| diff --git a/docs/c-runtime-library/reference/fread-nolock-s2.md b/docs/c-runtime-library/reference/fread-nolock-s2.md index ebf2b62d62a..ad8f91a34b0 100644 --- a/docs/c-runtime-library/reference/fread-nolock-s2.md +++ b/docs/c-runtime-library/reference/fread-nolock-s2.md @@ -40,7 +40,7 @@ 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 @@ -48,7 +48,7 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -56,7 +56,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fread_nolock_s**|C: \; C++: \ or \| +|**`_fread_nolock_s`**|C: \; C++: \ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fread-nolock.md b/docs/c-runtime-library/reference/fread-nolock.md index de9912aaaaf..1d242ed6cdc 100644 --- a/docs/c-runtime-library/reference/fread-nolock.md +++ b/docs/c-runtime-library/reference/fread-nolock.md @@ -37,7 +37,7 @@ Item size in bytes. Maximum number of items to be read. *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## Return value @@ -45,7 +45,7 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -53,7 +53,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fread_nolock**|\| +|**`_fread_nolock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fread-s.md b/docs/c-runtime-library/reference/fread-s.md index a167adbe065..7eb9e5d1be2 100644 --- a/docs/c-runtime-library/reference/fread-s.md +++ b/docs/c-runtime-library/reference/fread-s.md @@ -39,11 +39,11 @@ 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 -**`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. +**`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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/fread.md b/docs/c-runtime-library/reference/fread.md index 914f545d684..a627cc91c34 100644 --- a/docs/c-runtime-library/reference/fread.md +++ b/docs/c-runtime-library/reference/fread.md @@ -37,11 +37,11 @@ Item size in bytes. Maximum number of items to be read. *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## 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](../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 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](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -49,7 +49,7 @@ For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlis 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's one) is increased by the number of bytes actually 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 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. +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`**. diff --git a/docs/c-runtime-library/reference/free-dbg.md b/docs/c-runtime-library/reference/free-dbg.md index d9053e96594..e49438e1050 100644 --- a/docs/c-runtime-library/reference/free-dbg.md +++ b/docs/c-runtime-library/reference/free-dbg.md @@ -29,15 +29,15 @@ void _free_dbg( 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**. +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`](../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) 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. -**_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`](../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 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`](../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`](../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). @@ -45,13 +45,13 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_free_dbg**|\| +|**`_free_dbg`**|\| 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 diff --git a/docs/c-runtime-library/reference/free-locale.md b/docs/c-runtime-library/reference/free-locale.md index ca9ffee1683..506c6386207 100644 --- a/docs/c-runtime-library/reference/free-locale.md +++ b/docs/c-runtime-library/reference/free-locale.md @@ -29,17 +29,17 @@ 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 behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|**Routine**|Required header| +|`Routine`|Required header| |---------------|---------------------| -|**_free_locale**|\| +|**`_free_locale`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/free.md b/docs/c-runtime-library/reference/free.md index 058c1aaa004..21463c7e922 100644 --- a/docs/c-runtime-library/reference/free.md +++ b/docs/c-runtime-library/reference/free.md @@ -28,9 +28,9 @@ 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, 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. -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). +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. diff --git a/docs/c-runtime-library/reference/freea.md b/docs/c-runtime-library/reference/freea.md index bd74759c5f8..4faedfec3dc 100644 --- a/docs/c-runtime-library/reference/freea.md +++ b/docs/c-runtime-library/reference/freea.md @@ -33,23 +33,23 @@ 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 was not 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`](../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. -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 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). -**_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 \| +|**`_freea`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.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 16c05c2cdb6..636c7c1820b 100644 --- a/docs/c-runtime-library/reference/freopen-s-wfreopen-s.md +++ b/docs/c-runtime-library/reference/freopen-s-wfreopen-s.md @@ -49,7 +49,7 @@ 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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -59,13 +59,13 @@ 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](../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 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| +|`TCHAR.H` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_tfreopen_s`**|**`freopen_s`**|**`freopen_s`**|**`_wfreopen_s`**| @@ -95,7 +95,7 @@ When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both re 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. -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`**. +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). diff --git a/docs/c-runtime-library/reference/freopen-wfreopen.md b/docs/c-runtime-library/reference/freopen-wfreopen.md index 8333950bea6..3f0340656a5 100644 --- a/docs/c-runtime-library/reference/freopen-wfreopen.md +++ b/docs/c-runtime-library/reference/freopen-wfreopen.md @@ -37,11 +37,11 @@ Path of new file. Type of access permitted. *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -85,7 +85,7 @@ When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both re 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. -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`**. +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). diff --git a/docs/c-runtime-library/reference/frexp.md b/docs/c-runtime-library/reference/frexp.md index a3440935884..fe0165bc8b4 100644 --- a/docs/c-runtime-library/reference/frexp.md +++ b/docs/c-runtime-library/reference/frexp.md @@ -53,13 +53,13 @@ Pointer to stored integer exponent. ## 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](../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](../tgmath.md) for details. @@ -69,8 +69,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**frexp**, **frexpf**, **frexpl**|\| -|**frexp** macro | \ | +|**`frexp`**, **`frexpf`**, **`frexpl`**|\| +|**`frexp`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.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 b40daa453ca..bfa267d3127 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. @@ -56,9 +56,9 @@ The locale to use. ## 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](../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 @@ -70,7 +70,7 @@ The versions of these functions with the **`_l`** suffix are identical except th ### 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| |---------------------|------------------------------------|--------------------|-----------------------| |**`_ftscanf`**|**`fscanf`**|**`fscanf`**|**`fwscanf`**| |**`_ftscanf_l`**|**`_fscanf_l`**|**`_fscanf_l`**|**`_fwscanf_l`**| 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 76aa159481c..da46c810817 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 @@ -44,7 +44,7 @@ int _fwscanf_s_l( ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. *`format`*\ Format-control string. @@ -57,9 +57,9 @@ The locale to use. ## 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 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`**. -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`**. +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 diff --git a/docs/c-runtime-library/reference/fseek-fseeki64.md b/docs/c-runtime-library/reference/fseek-fseeki64.md index a4eeaf97629..973ff20343f 100644 --- a/docs/c-runtime-library/reference/fseek-fseeki64.md +++ b/docs/c-runtime-library/reference/fseek-fseeki64.md @@ -32,7 +32,7 @@ int _fseeki64( ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. *`offset`*\ Number of bytes from *`origin`*. @@ -42,7 +42,7 @@ Initial position. ## 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](../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`* is not 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 @@ -50,9 +50,9 @@ The **`fseek`** and **`_fseeki64`** functions moves the file pointer (if any) as |origin value|Meaning| |-|-| -| **`SEEK_CUR`** | Current position of file pointer. | -| **`SEEK_END`** | End of file. | -| **`SEEK_SET`** | Beginning of file. | +| `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`*. 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 ec30dbd121f..d15220c619d 100644 --- a/docs/c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md +++ b/docs/c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md @@ -32,7 +32,7 @@ int _fseeki64_nolock( ### Parameters *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. *`offset`*\ Number of bytes from *`origin`*. @@ -54,7 +54,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fseek_nolock**, **_fseeki64_nolock**|\| +|**`_fseek_nolock`**, **`_fseeki64_nolock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fsetpos.md b/docs/c-runtime-library/reference/fsetpos.md index 1c419b5681b..75faa7d5ffa 100644 --- a/docs/c-runtime-library/reference/fsetpos.md +++ b/docs/c-runtime-library/reference/fsetpos.md @@ -26,20 +26,20 @@ int fsetpos( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`pos`*\ Position-indicator storage. ## 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 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). +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). 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 a call to **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 behavior, see [Global state in the CRT](../global-state.md). @@ -47,7 +47,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**fsetpos**|\| +|**`fsetpos`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fsopen-wfsopen.md b/docs/c-runtime-library/reference/fsopen-wfsopen.md index aefaf1aca85..2faaf4f750c 100644 --- a/docs/c-runtime-library/reference/fsopen-wfsopen.md +++ b/docs/c-runtime-library/reference/fsopen-wfsopen.md @@ -42,7 +42,7 @@ Type of sharing allowed. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -74,17 +74,17 @@ When a file is opened with the **"`a`"** or **"`a+`"** access type, all write op |**`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.| -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](../text-and-binary-mode-file-i-o.md). +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](../text-and-binary-mode-file-i-o.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.| +|`_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.| By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md b/docs/c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md index c3fb53c11fb..fc35d5e651a 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 @@ -52,7 +52,7 @@ Pointer to the structure to store results. ## 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](../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`, in the case of an invalid file descriptor, or to `EINVAL`, if *`buffer`* is `NULL`. ## Remarks @@ -63,7 +63,7 @@ The **`_fstat`** function obtains information about the open file associated wit | **`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. | @@ -75,9 +75,9 @@ Because `Stat.h` uses the [`_dev_t`](../standard-types.md) type, which is define **`_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. -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`**. +**`_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`**. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/ftell-ftelli64.md b/docs/c-runtime-library/reference/ftell-ftelli64.md index 41738a4a1d2..76e778a9b4c 100644 --- a/docs/c-runtime-library/reference/ftell-ftelli64.md +++ b/docs/c-runtime-library/reference/ftell-ftelli64.md @@ -27,11 +27,11 @@ __int64 _ftelli64( ### Parameters *`stream`*\ -Target **`FILE`** structure. +Target `FILE` structure. ## 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](../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. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.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 dbb79568bed..f0b5fc7999d 100644 --- a/docs/c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md +++ b/docs/c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md @@ -28,15 +28,15 @@ __int64 _ftelli64_nolock( ### Parameters *`stream`*\ -Target the **FILE** structure. +Target the `FILE` structure. ## 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -44,8 +44,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**ftell_nolock**|\|\| -|**_ftelli64_nolock**|\|\| +|**`ftell_nolock`**|\|\| +|**`_ftelli64_nolock`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md b/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md index ea0b50ce5c9..40cc0b856f9 100644 --- a/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md +++ b/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md @@ -25,24 +25,24 @@ void _ftime64( struct __timeb64 *timeptr ); ### Parameters *`timeptr`*\ -Pointer to a **_timeb**, **__timeb32**, or **__timeb64** structure. +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**).| +|`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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -50,9 +50,9 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_ftime**|\ and \| -|**_ftime32**|\ and \| -|**_ftime64**|\ and \| +|**`_ftime`**|\ and \| +|**`_ftime32`**|\ and \| +|**`_ftime64`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.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 c578ebfc306..cd9afd18762 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 @@ -25,28 +25,28 @@ errno_t _ftime64_s( struct __timeb64 *timeptr ); ### Parameters *`timeptr`*\ -Pointer to a **_timeb**, **__timeb32**, or **__timeb64** structure. +Pointer to a `_timeb`, `__timeb32`, or `__timeb64` structure. ## 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**).| +|`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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -54,9 +54,9 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_ftime_s**|\ and \| -|**_ftime32_s**|\ and \| -|**_ftime64_s**|\ and \| +|**`_ftime_s`**|\ and \| +|**`_ftime32_s`**|\ and \| +|**`_ftime64_s`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.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 4ad1d2cc019..fe3eeb7317d 100644 --- a/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md +++ b/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md @@ -12,7 +12,7 @@ ms.assetid: 81f72f85-07da-4f5c-866a-598e0fb03f6b --- # `_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 @@ -38,45 +38,45 @@ wchar_t *_wfullpath_dbg( ### 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. *`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**. +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**. +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**. +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**. +Line number in the source file where the allocation operation was requested or `NULL`. ## 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 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`. ## 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 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). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfullpath_dbg**|**_fullpath_dbg**|**_fullpath_dbg**|**_wfullpath_dbg**| +|`_tfullpath_dbg`|**`_fullpath_dbg`**|**`_fullpath_dbg`**|**`_wfullpath_dbg`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**_fullpath_dbg**|\| -|**_wfullpath_dbg**|\| +|**`_fullpath_dbg`**|\| +|**`_wfullpath_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fullpath-wfullpath.md b/docs/c-runtime-library/reference/fullpath-wfullpath.md index 6c7820b0352..85e5898c530 100644 --- a/docs/c-runtime-library/reference/fullpath-wfullpath.md +++ b/docs/c-runtime-library/reference/fullpath-wfullpath.md @@ -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. @@ -41,11 +41,11 @@ Maximum length of the absolute path name buffer (*`absPath`*). This length is in ## 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): @@ -61,9 +61,9 @@ By default, this function's global state is scoped to the application. To change **`_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 for debugging 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](../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 @@ -71,7 +71,7 @@ This function invokes the invalid parameter handler, as described in [Parameter |---------------------|--------------------------------------|--------------------|-----------------------| |**`_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 diff --git a/docs/c-runtime-library/reference/futime-futime32-futime64.md b/docs/c-runtime-library/reference/futime-futime32-futime64.md index 7a1a8601704..4ee03c73ee5 100644 --- a/docs/c-runtime-library/reference/futime-futime32-futime64.md +++ b/docs/c-runtime-library/reference/futime-futime32-futime64.md @@ -41,13 +41,13 @@ Pointer to the structure containing the new modification date. ## Return value -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. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -55,9 +55,9 @@ By default, this function's global state is scoped to the application. To change |Function|Required header|Optional header| |--------------|---------------------|---------------------| -|**_futime**|\|\| -|**_futime32**|\|\| -|**_futime64**|\|\| +|**`_futime`**|\|\| +|**`_futime32`**|\|\| +|**`_futime64`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fwide.md b/docs/c-runtime-library/reference/fwide.md index 03719e8ff17..0c65c9d1a12 100644 --- a/docs/c-runtime-library/reference/fwide.md +++ b/docs/c-runtime-library/reference/fwide.md @@ -26,7 +26,7 @@ int fwide( ### Parameters *`stream`*\ -Pointer to **FILE** structure (ignored). +Pointer to `FILE` structure (ignored). *`mode`*\ The new width of the stream: positive for wide character, negative for byte, zero to leave unchanged. (This value is ignored.) @@ -43,6 +43,6 @@ The current version of this function doesn't conform to the C Standard. |Function|Required header| |--------------|---------------------| -|**fwide**|\| +|**`fwide`**|\| 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 626b1720c67..b966bfee7d4 100644 --- a/docs/c-runtime-library/reference/fwrite-nolock.md +++ b/docs/c-runtime-library/reference/fwrite-nolock.md @@ -37,7 +37,7 @@ Item size in bytes. Maximum number of items to be written. *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## Return value @@ -45,7 +45,7 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -53,7 +53,7 @@ By default, this function's global state is scoped to the application. To change |Function|Required header| |--------------|---------------------| -|**_fwrite_nolock**|\| +|**`_fwrite_nolock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fwrite.md b/docs/c-runtime-library/reference/fwrite.md index 551216269cb..546ec138182 100644 --- a/docs/c-runtime-library/reference/fwrite.md +++ b/docs/c-runtime-library/reference/fwrite.md @@ -37,17 +37,17 @@ Item size, in bytes. Maximum number of items to be written. *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## 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](../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 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](../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. -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`**. diff --git a/docs/c-runtime-library/reference/gcvt-s.md b/docs/c-runtime-library/reference/gcvt-s.md index 7fab033b02a..cbe09f658ba 100644 --- a/docs/c-runtime-library/reference/gcvt-s.md +++ b/docs/c-runtime-library/reference/gcvt-s.md @@ -53,17 +53,17 @@ Zero if successful. If a failure occurs due to an invalid parameter (see the fol |*`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.| +|`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`* does not point to valid memory and is not `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 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. 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). @@ -75,7 +75,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_gcvt_s**|\|\| +|**`_gcvt_s`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/gcvt.md b/docs/c-runtime-library/reference/gcvt.md index 609619267b2..14e5de140d3 100644 --- a/docs/c-runtime-library/reference/gcvt.md +++ b/docs/c-runtime-library/reference/gcvt.md @@ -37,15 +37,15 @@ Storage location for the result. ## 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. 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. -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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -53,7 +53,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_gcvt**|\| +|**`_gcvt`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-current-locale.md b/docs/c-runtime-library/reference/get-current-locale.md index 2bb4ae41cc0..46555231fb6 100644 --- a/docs/c-runtime-library/reference/get-current-locale.md +++ b/docs/c-runtime-library/reference/get-current-locale.md @@ -26,15 +26,15 @@ 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**|\| +|**`_get_current_locale`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-daylight.md b/docs/c-runtime-library/reference/get-daylight.md index a205d1a5880..a151f481e83 100644 --- a/docs/c-runtime-library/reference/get-daylight.md +++ b/docs/c-runtime-library/reference/get-daylight.md @@ -27,15 +27,15 @@ The offset in hours of daylight saving time. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_daylight**|\| +|**`_get_daylight`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-doserrno.md b/docs/c-runtime-library/reference/get-doserrno.md index e5583ea5856..7a4cf3f437d 100644 --- a/docs/c-runtime-library/reference/get-doserrno.md +++ b/docs/c-runtime-library/reference/get-doserrno.md @@ -12,7 +12,7 @@ ms.assetid: 7fec7be3-6e39-4181-846b-8ef24489361c --- # `_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 is translated into an `errno` value. ## Syntax @@ -25,19 +25,19 @@ errno_t _get_doserrno( ### Parameters *`pValue`*\ -A pointer to an integer to be filled with the current value of the **_doserrno** global macro. +A pointer to an integer to be filled with the current value of the `_doserrno` global macro. ## 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](../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 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. -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 behavior, see [Global state in the CRT](../global-state.md). @@ -45,9 +45,9 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_get_doserrno**|\, \ (C++)|\, \ (C++)| +|**`_get_doserrno`**|\, \ (C++)|\, \ (C++)| -**_get_doserrno** is a Microsoft extension. For more compatibility information, see [Compatibility](../compatibility.md). +**`_get_doserrno`** is a Microsoft extension. For more compatibility information, see [Compatibility](../compatibility.md). ## See also diff --git a/docs/c-runtime-library/reference/get-dstbias.md b/docs/c-runtime-library/reference/get-dstbias.md index 3e6236f96eb..39f88eb0ff0 100644 --- a/docs/c-runtime-library/reference/get-dstbias.md +++ b/docs/c-runtime-library/reference/get-dstbias.md @@ -26,13 +26,13 @@ The offset in seconds of daylight saving time. ## 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](../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`**. diff --git a/docs/c-runtime-library/reference/get-errno.md b/docs/c-runtime-library/reference/get-errno.md index 9d41ffc969b..1dd02217962 100644 --- a/docs/c-runtime-library/reference/get-errno.md +++ b/docs/c-runtime-library/reference/get-errno.md @@ -25,15 +25,15 @@ errno_t _get_errno( ### Parameters *`pValue`*\ -A pointer to an integer to be filled with the current value of the **errno** variable. +A pointer to an integer to be filled with the current value of the `errno` variable. ## 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](../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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -67,7 +67,7 @@ fyi, ENOENT = 2 |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_get_errno**|\|\| +|**`_get_errno`**|\|\| For more compatibility information, see [Compatibility](../compatibility.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 b60c2144151..a973a0a2750 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 @@ -32,19 +32,19 @@ A non-zero value if the FMA3 implementations of the transcendental math floating ## 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 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. 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). ## 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 \| +|**`_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](../compatibility.md). +The **`_set_FMA3_enable`** and **`_get_FMA3_enable`** functions are Microsoft-specific. For compatibility information, see [Compatibility](../compatibility.md). ## See also diff --git a/docs/c-runtime-library/reference/get-fmode.md b/docs/c-runtime-library/reference/get-fmode.md index dc4080b9f41..49096bf1b91 100644 --- a/docs/c-runtime-library/reference/get-fmode.md +++ b/docs/c-runtime-library/reference/get-fmode.md @@ -25,15 +25,15 @@ errno_t _get_fmode( ### Parameters *`pmode`*\ -A pointer to an integer to be filled with the current default mode: **_O_TEXT** or **_O_BINARY**. +A pointer to an integer to be filled with the current default mode: `_O_TEXT` or `_O_BINARY`. ## 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](../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`](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_get_fmode**|\|\| +|**`_get_fmode`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-heap-handle.md b/docs/c-runtime-library/reference/get-heap-handle.md index b20465ae43b..e67d56edc23 100644 --- a/docs/c-runtime-library/reference/get-heap-handle.md +++ b/docs/c-runtime-library/reference/get-heap-handle.md @@ -34,7 +34,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_heap_handle**|\| +|**`_get_heap_handle`**|\| For more compatibility information, see [Compatibility](../compatibility.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 30c25ed450f..9a88e8beecb 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 @@ -27,7 +27,7 @@ A pointer to the currently set invalid parameter handler function, or a null poi ## 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 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 returned invalid parameter handler function pointer has the following type: @@ -49,9 +49,9 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_invalid_parameter_handler**, **_get_thread_local_invalid_parameter_handler**|C: \

C++: \ or \| +|**`_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](../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 diff --git a/docs/c-runtime-library/reference/get-osfhandle.md b/docs/c-runtime-library/reference/get-osfhandle.md index 1652dba7025..43f15939b3f 100644 --- a/docs/c-runtime-library/reference/get-osfhandle.md +++ b/docs/c-runtime-library/reference/get-osfhandle.md @@ -28,16 +28,16 @@ An existing file descriptor. ## Return value -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. +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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/get-pgmptr.md b/docs/c-runtime-library/reference/get-pgmptr.md index fed2319f71b..73664cd3122 100644 --- a/docs/c-runtime-library/reference/get-pgmptr.md +++ b/docs/c-runtime-library/reference/get-pgmptr.md @@ -12,7 +12,7 @@ ms.assetid: 29f16a9f-a685-4721-add3-7fad4f67eece --- # `_get_pgmptr` -Gets the current value of the **_pgmptr** global variable. +Gets the current value of the `_pgmptr` global variable. ## Syntax @@ -25,15 +25,15 @@ errno_t _get_pgmptr( ### Parameters *`pValue`*\ -A pointer to a string to be filled with the current value of the **_pgmptr** variable. +A pointer to a string to be filled with the current value of the `_pgmptr` variable. ## 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](../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`](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_pgmptr**|\| +|**`_get_pgmptr`**|\| For more compatibility information, see [Compatibility](../compatibility.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 8b3c3c28723..bebd78fa4da 100644 --- a/docs/c-runtime-library/reference/get-printf-count-output.md +++ b/docs/c-runtime-library/reference/get-printf-count-output.md @@ -25,7 +25,7 @@ Non-zero if **%n** is supported, 0 if **%n** is not 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](../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](../format-specification-syntax-printf-and-wprintf-functions.md). +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](../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](../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). @@ -34,7 +34,7 @@ If **%n** is not supported (the default), encountering **%n** in the format stri |Routine|Required header| |-------------|---------------------| -|**_get_printf_count_output**|\| +|**`_get_printf_count_output`**|\| For more compatibility information, see [Compatibility](../compatibility.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 f9cc60e2f67..7c81eccb6e3 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 @@ -27,27 +27,27 @@ _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. +The function to be called when a pure virtual function is called. A `_purecall_handler` function must have a void return type. ## 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 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. -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 \| +|**`_get_purecall_handler`**, **`_set_purecall_handler`**|\ or \| For compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-terminate.md b/docs/c-runtime-library/reference/get-terminate.md index 229380178d4..06f46f701d8 100644 --- a/docs/c-runtime-library/reference/get-terminate.md +++ b/docs/c-runtime-library/reference/get-terminate.md @@ -12,7 +12,7 @@ ms.assetid: c8f168c4-0ad5-4832-a522-dd1ef383c208 --- # `_get_terminate` -Returns the termination routine to be called by **terminate**. +Returns the termination routine to be called by `terminate`. ## Syntax @@ -22,7 +22,7 @@ terminate_function _get_terminate( void ); ## 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 @@ -32,7 +32,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_terminate**|\| +|**`_get_terminate`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-timezone.md b/docs/c-runtime-library/reference/get-timezone.md index 05c1e9f9e24..6e77af1d97f 100644 --- a/docs/c-runtime-library/reference/get-timezone.md +++ b/docs/c-runtime-library/reference/get-timezone.md @@ -29,13 +29,13 @@ The difference in seconds between UTC and local time. ## 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 *`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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_timezone**|\| +|**`_get_timezone`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/get-tzname.md b/docs/c-runtime-library/reference/get-tzname.md index 3dcefcf7f1e..2eae72afe75 100644 --- a/docs/c-runtime-library/reference/get-tzname.md +++ b/docs/c-runtime-library/reference/get-tzname.md @@ -42,7 +42,7 @@ The *`index`* of one of the two time zone names to retrieve. |-|-|-| |0|Time zone name|`"PST"`| |1|Daylight standard time zone name|`"PDT"`| -|> 1 or < 0|**`errno`** set to `EINVAL`|not modified| +|> 1 or < 0|`errno` set to `EINVAL`|not modified| 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). @@ -50,9 +50,9 @@ The time zone string isn't guaranteed to be the same between OS releases. Offici ## Return value -Zero if successful, otherwise an **`errno`** type value. +Zero if successful, otherwise an `errno` type 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](../parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to `EINVAL` and returns `EINVAL`. +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`. ### Error conditions diff --git a/docs/c-runtime-library/reference/get-unexpected.md b/docs/c-runtime-library/reference/get-unexpected.md index 8b35b845234..0b2d3861a52 100644 --- a/docs/c-runtime-library/reference/get-unexpected.md +++ b/docs/c-runtime-library/reference/get-unexpected.md @@ -22,7 +22,7 @@ unexpected_function _get_unexpected( void ); ## 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 diff --git a/docs/c-runtime-library/reference/get-wpgmptr.md b/docs/c-runtime-library/reference/get-wpgmptr.md index 1be18f64ee6..33ef9ffe44b 100644 --- a/docs/c-runtime-library/reference/get-wpgmptr.md +++ b/docs/c-runtime-library/reference/get-wpgmptr.md @@ -12,7 +12,7 @@ ms.assetid: a77cdd13-2303-4b7c-9a60-8debdbef2011 --- # `_get_wpgmptr` -Gets the current value of the **_wpgmptr** global variable. +Gets the current value of the `_wpgmptr` global variable. ## Syntax @@ -25,15 +25,15 @@ errno_t _get_wpgmptr( ### Parameters *`pValue`*\ -A pointer to a string to be filled with the current value of the **_wpgmptr** variable. +A pointer to a string to be filled with the current value of the `_wpgmptr` variable. ## 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](../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`](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_get_wpgmptr**|\| +|**`_get_wpgmptr`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getc-getwc.md b/docs/c-runtime-library/reference/getc-getwc.md index d47fd28eb25..8f263439fcf 100644 --- a/docs/c-runtime-library/reference/getc-getwc.md +++ b/docs/c-runtime-library/reference/getc-getwc.md @@ -32,7 +32,7 @@ Input stream. ## 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](../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`. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -46,23 +46,23 @@ 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.| +|**`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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_gettc**|**getc**|**getc**|**getwc**| +|`_gettc`|**`getc`**|**`getc`**|**`getwc`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**getc**|\| -|**getwc**|\ or \| +|**`getc`**|\| +|**`getwc`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 291161ce33e..d6d4356ab49 100644 --- a/docs/c-runtime-library/reference/getc-nolock-getwc-nolock.md +++ b/docs/c-runtime-library/reference/getc-nolock-getwc-nolock.md @@ -36,22 +36,22 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettc_nolock**|**getc_nolock**|**getc_nolock**|**getwc_nolock**| +|`_gettc_nolock`|**`getc_nolock`**|**`getc_nolock`**|**`getwc_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**getc_nolock**|\| -|**getwc_nolock**|\ or \| +|**`getc_nolock`**|\| +|**`getwc_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 1623f931ff7..eab881bb2bc 100644 --- a/docs/c-runtime-library/reference/getch-nolock-getwch-nolock.md +++ b/docs/c-runtime-library/reference/getch-nolock-getwch-nolock.md @@ -30,22 +30,22 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettch_nolock**|**_getch_nolock**|**_getch_nolock**|**_getwch_nolock**| +|`_gettch_nolock`|**`_getch_nolock`**|**`_getch_nolock`**|**`_getwch_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getch_nolock**|\| -|**_getwch_nolock**|\ or \| +|**`_getch_nolock`**|\| +|**`_getwch_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getchar-getwchar.md b/docs/c-runtime-library/reference/getchar-getwchar.md index ca7f3c9fc59..4bbd7fd77d8 100644 --- a/docs/c-runtime-library/reference/getchar-getwchar.md +++ b/docs/c-runtime-library/reference/getchar-getwchar.md @@ -24,7 +24,7 @@ wint_t getwchar(); 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 @@ -36,9 +36,9 @@ 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| +|`TCHAR.H` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**`_gettchar`**|**`getchar`**|**`getchar`**|**`getwchar`**| +|`_gettchar`|**`getchar`**|**`getchar`**|**`getwchar`**| ## Requirements 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 3490ce771c6..cc5987f5b97 100644 --- a/docs/c-runtime-library/reference/getchar-nolock-getwchar-nolock.md +++ b/docs/c-runtime-library/reference/getchar-nolock-getwchar-nolock.md @@ -27,22 +27,22 @@ 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 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. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettchar_nolock**|**_getchar_nolock**|**_getchar_nolock**|**_getwchar_nolock**| +|`_gettchar_nolock`|**`_getchar_nolock`**|**`_getchar_nolock`**|**`_getwchar_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getchar_nolock**|\| -|**_getwchar_nolock**|\ or \| +|**`_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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Example diff --git a/docs/c-runtime-library/reference/getche-getwche.md b/docs/c-runtime-library/reference/getche-getwche.md index 485a88c88bc..141abf66d22 100644 --- a/docs/c-runtime-library/reference/getche-getwche.md +++ b/docs/c-runtime-library/reference/getche-getwche.md @@ -30,7 +30,7 @@ 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 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. 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). @@ -38,16 +38,16 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_getche**|**_getche**|**_getch**|**_getwche**| +|`_gettche`|**`_getche`**|**`_getche`**|**`_getwche`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getche**|\| -|**_getwche**|\ or \| +|**`_getche`**|\| +|**`_getwche`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 21fbd89a0ae..1d69fc47ec1 100644 --- a/docs/c-runtime-library/reference/getche-nolock-getwche-nolock.md +++ b/docs/c-runtime-library/reference/getche-nolock-getwche-nolock.md @@ -30,22 +30,22 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettche_nolock**|**_getche_nolock**|**_getch_nolock**|**_getwche_nolock**| +|`_gettche_nolock`|**`_getche_nolock`**|**`_getch_nolock`**|**`_getwche_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getche_nolock**|\| -|**_getwche_nolock**|\ or \| +|**`_getche_nolock`**|\| +|**`_getwche_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 082a82b8754..cdd6697c92a 100644 --- a/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md +++ b/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md @@ -39,41 +39,41 @@ wchar_t *_wgetcwd_dbg( Storage location for the path. *`maxlen`*\ -Maximum length of the path in characters: **`char`** for **_getcwd_dbg** and **`wchar_t`** for **_wgetcwd_dbg**. +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**. +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**. +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**. +Line number in the source file where the allocation operation was requested or `NULL`. ## 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 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`](../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 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). ## Generic-text routine mapping -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetcwd_dbg**|**_getcwd_dbg**|**_getcwd_dbg**|**_wgetcwd_dbg**| +|`_tgetcwd_dbg`|**`_getcwd_dbg`**|**`_getcwd_dbg`**|**`_wgetcwd_dbg`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getcwd_dbg**|\| -|**_wgetcwd_dbg**|\| +|**`_getcwd_dbg`**|\| +|**`_wgetcwd_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getcwd-wgetcwd.md b/docs/c-runtime-library/reference/getcwd-wgetcwd.md index 96cc1ab8823..a95233979ba 100644 --- a/docs/c-runtime-library/reference/getcwd-wgetcwd.md +++ b/docs/c-runtime-library/reference/getcwd-wgetcwd.md @@ -37,19 +37,19 @@ Maximum length of the path in characters: **`char`** for **`_getcwd`** and **`wc ## 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](../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 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](../parameter-validation.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 for debugging 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 behavior, see [Global state in the CRT](../global-state.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 1a478978d18..82f40eaf8ac 100644 --- a/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md +++ b/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md @@ -44,39 +44,39 @@ Name of the disk drive. Storage location for the path. *`maxlen`*\ -Maximum length of the path in characters: **`char`** for **_getdcwd_dbg** and **`wchar_t`** for **_wgetdcwd_dbg**. +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**. +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**. +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**. +Line number in the source file where the allocation operation was requested or `NULL`. ## 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`](../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 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`](../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 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). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetdcwd_dbg**|**_getdcwd_dbg**|**_getdcwd_dbg**|**_wgetdcwd_dbg**| +|**`_tgetdcwd_dbg`**|**`_getdcwd_dbg`**|**`_getdcwd_dbg`**|**`_wgetdcwd_dbg`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getdcwd_dbg**|\| -|**_wgetdcwd_dbg**|\| +|**`_getdcwd_dbg`**|\| +|**`_wgetdcwd_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.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 856e8326155..308921623fb 100644 --- a/docs/c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md +++ b/docs/c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md @@ -41,7 +41,7 @@ Disk drive. Storage location for the path. *`maxlen`*\ -Maximum length of path in characters: **`char`** for **_getdcwd** and **`wchar_t`** for **_wgetdcwd**. +Maximum length of path in characters: **`char`** for **`_getdcwd_nolock`** and **`wchar_t`** for **`_wgetdcwd_nolock`**. ## Return value @@ -49,20 +49,20 @@ 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 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. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetdcwd_nolock**|**_getdcwd_nolock**|**_getdcwd_nolock**|**_wgetdcwd_nolock**| +|**`_tgetdcwd_nolock`**|**`_getdcwd_nolock`**|**`_getdcwd_nolock`**|**`_wgetdcwd_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getdcwd_nolock**|\| -|**_wgetdcwd_nolock**|\ or \| +|**`_getdcwd_nolock`**|\| +|**`_wgetdcwd_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md b/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md index 7bec1211747..11909a33222 100644 --- a/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md +++ b/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md @@ -37,47 +37,47 @@ A non-negative integer that specifies the drive (0 = default drive, 1 = A, 2 = B 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](../parameter-validation.md). *`buffer`*\ -Storage location for the path, or **NULL**. +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**. +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](../parameter-validation.md). ## 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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). +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`](../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 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). -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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetdcwd**|**_getdcwd**|**_getdcwd**|**_wgetdcwd**| +|`_tgetdcwd`|**`_getdcwd`**|**`_getdcwd`**|**`_wgetdcwd`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_getdcwd**|\| -|**_wgetdcwd**|\ or \| +|**`_getdcwd`**|\| +|**`_wgetdcwd`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getdiskfree.md b/docs/c-runtime-library/reference/getdiskfree.md index 184f9a930ba..c6dd6d6f5b5 100644 --- a/docs/c-runtime-library/reference/getdiskfree.md +++ b/docs/c-runtime-library/reference/getdiskfree.md @@ -35,7 +35,7 @@ A **`_diskfree_t`** structure that will be populated with information about the ## 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](../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,7 +50,7 @@ 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](../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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/getdrive.md b/docs/c-runtime-library/reference/getdrive.md index bd29f734ce1..c758863bd2b 100644 --- a/docs/c-runtime-library/reference/getdrive.md +++ b/docs/c-runtime-library/reference/getdrive.md @@ -35,7 +35,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_getdrive**|\| +|**`_getdrive`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getdrives.md b/docs/c-runtime-library/reference/getdrives.md index f5acad1e753..880a4f016b8 100644 --- a/docs/c-runtime-library/reference/getdrives.md +++ b/docs/c-runtime-library/reference/getdrives.md @@ -25,7 +25,7 @@ unsigned long _getdrives( void ); ## 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) 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`. ## Remarks @@ -35,7 +35,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_getdrives**|\| +|**`_getdrives`**|\| For more compatibility information, see [Compatibility](../compatibility.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 9d618adeef0..34541e1bd00 100644 --- a/docs/c-runtime-library/reference/getenv-s-wgetenv-s.md +++ b/docs/c-runtime-library/reference/getenv-s-wgetenv-s.md @@ -68,13 +68,13 @@ Zero if successful; otherwise, an error code on failure. |*`pReturnValue`*|*`buffer`*|*`numberOfElements`*|*`varname`*|Return Value| |--------------------|--------------|------------------------|---------------|------------------| -|**`NULL`**|any|any|any|**`EINVAL`**| -|any|**`NULL`**|>0|any|**`EINVAL`**| -|any|any|any|**`NULL`**|**`EINVAL`**| +|`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](../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,9 +82,9 @@ 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. diff --git a/docs/c-runtime-library/reference/getenv-wgetenv.md b/docs/c-runtime-library/reference/getenv-wgetenv.md index a495f4d0386..94593d5576f 100644 --- a/docs/c-runtime-library/reference/getenv-wgetenv.md +++ b/docs/c-runtime-library/reference/getenv-wgetenv.md @@ -36,19 +36,19 @@ 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 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. ## 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. -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`**. +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. diff --git a/docs/c-runtime-library/reference/getmaxstdio.md b/docs/c-runtime-library/reference/getmaxstdio.md index a04512a945a..79236d75b3c 100644 --- a/docs/c-runtime-library/reference/getmaxstdio.md +++ b/docs/c-runtime-library/reference/getmaxstdio.md @@ -22,17 +22,17 @@ int _getmaxstdio( void ); ## 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**|\| +|**`_getmaxstdio`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/getmbcp.md b/docs/c-runtime-library/reference/getmbcp.md index 6944b91004b..f2f7c9836dc 100644 --- a/docs/c-runtime-library/reference/getmbcp.md +++ b/docs/c-runtime-library/reference/getmbcp.md @@ -32,7 +32,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_getmbcp**|\| +|**`_getmbcp`**|\| For more compatibility information, see [Compatibility](../compatibility.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 1f04e5cc0a1..2befc9abe27 100644 --- a/docs/c-runtime-library/reference/gets-s-getws-s.md +++ b/docs/c-runtime-library/reference/gets-s-getws-s.md @@ -45,17 +45,17 @@ The size of the buffer. ## 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](../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](../secure-template-overloads.md). diff --git a/docs/c-runtime-library/reference/getw.md b/docs/c-runtime-library/reference/getw.md index 4497dd15219..c5c7269ef29 100644 --- a/docs/c-runtime-library/reference/getw.md +++ b/docs/c-runtime-library/reference/getw.md @@ -25,15 +25,15 @@ int _getw( ### Parameters *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## 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](../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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_getw**|\| +|**`_getw`**|\| For more compatibility information, see [Compatibility](../compatibility.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 e6272520b9e..d16c0d1adff 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 @@ -46,11 +46,11 @@ Zero if successful. The return value is an error code if there's a failure. Erro |*`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.| +|`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](../parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +In the case of the first two error conditions, 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 @@ -75,7 +75,7 @@ Each of the structure fields is of type **`int`**, as shown in the following tab **`_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. +**`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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/heapchk.md b/docs/c-runtime-library/reference/heapchk.md index ed59aca5d74..c4eb12a2221 100644 --- a/docs/c-runtime-library/reference/heapchk.md +++ b/docs/c-runtime-library/reference/heapchk.md @@ -22,21 +22,21 @@ int _heapchk( void ); ## 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. | +| `_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. | -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 does not support **`_heapchk`**(for example, Windows 98), the function returns `_HEAPOK` and sets `errno` to `ENOSYS`. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -44,7 +44,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_heapchk**|\|\| +|**`_heapchk`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/heapmin.md b/docs/c-runtime-library/reference/heapmin.md index 47218939c50..0ac1d0d1e46 100644 --- a/docs/c-runtime-library/reference/heapmin.md +++ b/docs/c-runtime-library/reference/heapmin.md @@ -22,13 +22,13 @@ int _heapmin( void ); ## 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 [`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 does not support **`_heapmin`**(for example, Windows 98), the function returns -1 and sets `errno` to `ENOSYS`. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -36,7 +36,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_heapmin**|\|\| +|**`_heapmin`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/heapwalk.md b/docs/c-runtime-library/reference/heapwalk.md index dd65b6f3805..07284fdaa6f 100644 --- a/docs/c-runtime-library/reference/heapwalk.md +++ b/docs/c-runtime-library/reference/heapwalk.md @@ -30,22 +30,22 @@ Buffer to contain heap information. ## 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.| +|`_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.| -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| |-|-| @@ -53,15 +53,15 @@ The **_heapwalk** function helps debug heap-related problems in programs. The fu |`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 does not support **`_heapwalk`**(for example, Windows 98), 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](../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**|\|\| +|**`_heapwalk`**|\|\| For more compatibility information, see [Compatibility](../compatibility.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 172aad43be1..571a5c4270d 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 @@ -51,13 +51,13 @@ Floating-point values. ## 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`](../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. @@ -69,8 +69,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**hypot**, **hypotf**, **hypotl**, **_hypot**, **_hypotf**, **_hypotl**|\| -|**hypot** macro | \ | +|**`hypot`**, **`hypotf`**, **`hypotl`**, **`_hypot`**, **`_hypotf`**, **`_hypotl`**|\| +|**`hypot`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md b/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md index 75658943f9e..fc75de562fb 100644 --- a/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md +++ b/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md @@ -60,18 +60,18 @@ 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](../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 | \ || +|**`ilogb`**, **`ilogbf`**, **`ilogbl`**|\|\| +|**`ilogb`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/imaxabs.md b/docs/c-runtime-library/reference/imaxabs.md index 1b8c4100302..2aa92d08e72 100644 --- a/docs/c-runtime-library/reference/imaxabs.md +++ b/docs/c-runtime-library/reference/imaxabs.md @@ -29,16 +29,16 @@ Integer 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**|\| +|**`imaxabs`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/imaxdiv.md b/docs/c-runtime-library/reference/imaxdiv.md index d0e47ebd42c..f1bcf4781f9 100644 --- a/docs/c-runtime-library/reference/imaxdiv.md +++ b/docs/c-runtime-library/reference/imaxdiv.md @@ -33,17 +33,17 @@ The denominator. ## Return value -**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. +**`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 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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**imaxdiv**|\| +|**`imaxdiv`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/initterm-initterm-e.md b/docs/c-runtime-library/reference/initterm-initterm-e.md index 642094585fc..a868183586e 100644 --- a/docs/c-runtime-library/reference/initterm-initterm-e.md +++ b/docs/c-runtime-library/reference/initterm-initterm-e.md @@ -38,7 +38,7 @@ A non-zero error code if an initialization fails and throws an error; 0 if no er These methods are only called internally during the initialization of a C++ program. Do not 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 diff --git a/docs/c-runtime-library/reference/invalid-parameter-functions.md b/docs/c-runtime-library/reference/invalid-parameter-functions.md index cbb67bd8905..dc622c64725 100644 --- a/docs/c-runtime-library/reference/invalid-parameter-functions.md +++ b/docs/c-runtime-library/reference/invalid-parameter-functions.md @@ -67,7 +67,7 @@ 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 behavior, see [Global state in the CRT](../global-state.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 74d4917b3c7..be385f83817 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 @@ -33,18 +33,18 @@ The locale to use. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istalnum**|**isalnum**|[`_ismbcalnum`](ismbcalnum-functions.md)|**iswalnum**| -|**_istalnum_l**|**_isalnum_l**|**_ismbcalnum_l**|**_iswalnum_l**| +|`_istalnum`|**`isalnum`**|[`_ismbcalnum`](ismbcalnum-functions.md)|**`iswalnum`**| +|**`_istalnum_l`**|**`_isalnum_l`**|**`_ismbcalnum_l`**|**`_iswalnum_l`**| ## Remarks @@ -54,10 +54,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isalnum**|\| -|**iswalnum**|\ or \| -|**_isalnum_l**|\| -|**_iswalnum_l**|\ or \| +|**`isalnum`**|\| +|**`iswalnum`**|\ or \| +|**`_isalnum_l`**|\| +|**`_iswalnum_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 241ca6e9896..5a4666dd8bf 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 @@ -43,18 +43,18 @@ The locale to use instead of the current locale. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istalpha**|**isalpha**|**_ismbcalpha**|**iswalpha**| -|**_istalpha_l**|**_isalpha_l**|**_ismbcalpha_l**|**_iswalpha_l**| +|`_istalpha`|**`isalpha`**|**`_ismbcalpha`**|**`iswalpha`**| +|`_istalpha_l`|**`_isalpha_l`**|**`_ismbcalpha_l`**|**`_iswalpha_l`**| ## Remarks @@ -64,10 +64,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isalpha**|\| -|**iswalpha**|\ or \| -|**_isalpha_l**|\| -|**_iswalpha_l**|\ or \| +|**`isalpha`**|\| +|**`iswalpha`**|\ or \| +|**`_isalpha_l`**|\| +|**`_iswalpha_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/isascii-isascii-iswascii.md b/docs/c-runtime-library/reference/isascii-isascii-iswascii.md index 581a9b33442..9ed6c8ebd38 100644 --- a/docs/c-runtime-library/reference/isascii-isascii-iswascii.md +++ b/docs/c-runtime-library/reference/isascii-isascii-iswascii.md @@ -46,7 +46,7 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| |**`_istascii`**|**`__isascii`**|**`__isascii`**|**`iswascii`**| diff --git a/docs/c-runtime-library/reference/isatty.md b/docs/c-runtime-library/reference/isatty.md index 6c076f38b37..561cfdf7bbb 100644 --- a/docs/c-runtime-library/reference/isatty.md +++ b/docs/c-runtime-library/reference/isatty.md @@ -27,13 +27,13 @@ File descriptor that refers to the device to be tested. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_isatty**|\| +|**`_isatty`**|\| For more compatibility information, see [Compatibility](../compatibility.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 147e212a9a0..8810f8d04ae 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 @@ -42,18 +42,18 @@ Locale to use. ## 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](../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 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istblank**|**isblank**|[`_ismbcblank`](ismbcgraph-functions.md)|**iswblank**| -|**_istblank_l**|**_isblank_l**|[`_ismbcblank_l`](ismbcgraph-functions.md)|**_iswblank_l**| +|`_istblank`|**`isblank`**|[`_ismbcblank`](ismbcgraph-functions.md)|**`iswblank`**| +|**`_istblank_l`**|**`_isblank_l`**|[`_ismbcblank_l`](ismbcgraph-functions.md)|**`_iswblank_l`**| ## Remarks @@ -63,10 +63,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isblank**|\| -|**iswblank**|\ or \| -|**_isblank_l**|\| -|**_iswblank_l**|\ or \| +|**`isblank`**|\| +|**`iswblank`**|\ or \| +|**`_isblank_l`**|\| +|**`_iswblank_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 27174a3c901..8624446b07f 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 @@ -43,18 +43,18 @@ The locale to use. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istcntrl**|**iscntrl**|**iscntrl**|**iswcntrl**| -|**_istcntrl_l**|**_iscntrl_l**|**_iscntrl_l**|**_iswcntrl_l**| +|`_istcntrl`|**`iscntrl`**|**`iscntrl`**|**`iswcntrl`**| +|`_istcntrl_l`|**`_iscntrl_l`**|**`_iscntrl_l`**|**`_iswcntrl_l`**| ## Remarks @@ -64,10 +64,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**iscntrl**|\| -|**iswcntrl**|\ or \| -|**_iscntrl_l**|\| -|**_iswcntrl_l**|\ or \| +|**`iscntrl`**|\| +|**`iswcntrl`**|\ or \| +|**`_iscntrl_l`**|\| +|**`_iswcntrl_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/iscsym-functions.md b/docs/c-runtime-library/reference/iscsym-functions.md index 12edb7f7496..7aa2cdc5647 100644 --- a/docs/c-runtime-library/reference/iscsym-functions.md +++ b/docs/c-runtime-library/reference/iscsym-functions.md @@ -59,21 +59,21 @@ The locale to use. ## 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](../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`* 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](../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) is not defined or is defined as 0; otherwise they are undefined. ## Requirements |Routine|Required header| |-------------|---------------------| -|**iscsym**, **iscsymf**, **__iscsym**, **__iswcsym**, **__iscsymf**, **__iswcsymf**, **_iscsym_l**, **_iswcsym_l**, **_iscsymf_l**, **_iswcsymf_l**|C: \

C++: \ or \| +|**`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 more compatibility information, see [Compatibility](../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 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 6004bb4814a..e2084391d96 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 @@ -50,16 +50,16 @@ The locale to use for any locale-dependent tests. ## 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](../locale.md). +**`_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](../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`* 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. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|n/a|**_isctype**|n/a|**_iswctype**| -|n/a|**_isctype_l**|n/a|**_iswctype_l**| +|n/a|**`_isctype`**|n/a|**`_iswctype`**| +|n/a|**`_isctype_l`**|n/a|**`_iswctype_l`**| ## Remarks @@ -69,10 +69,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_isctype**|\| -|**iswctype**|\ or \| -|**_isctype_l**|\| -|**_iswctype_l**|\ or \| +|**`_isctype`**|\| +|**`iswctype`**|\ or \| +|**`_isctype_l`**|\| +|**`_iswctype_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 20631208cf9..3ed3eecbd9b 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 @@ -43,18 +43,18 @@ The locale to use. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istdigit**|**isdigit**|[`_ismbcdigit`](ismbcalnum-functions.md)|**iswdigit**| -|**_istdigit_l**|**_isdigit_l**|[`_ismbcdigit_l`](ismbcalnum-functions.md)|**_iswdigit_l**| +|`_istdigit`|**`isdigit`**|[`_ismbcdigit`](ismbcalnum-functions.md)|**`iswdigit`**| +|`_istdigit_l`|**`_isdigit_l`**|[`_ismbcdigit_l`](ismbcalnum-functions.md)|**`_iswdigit_l`**| ## Remarks @@ -64,10 +64,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isdigit**|\| -|**iswdigit**|\ or \| -|**_isdigit_l**|\| -|**_iswdigit_l**|\ or \| +|**`isdigit`**|\| +|**`iswdigit`**|\ or \| +|**`_isdigit_l`**|\| +|**`_iswdigit_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 6046cde38e0..e1dbae8a6dc 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 @@ -40,18 +40,18 @@ Integer to test. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istgraph**|**isgraph**|[`_ismbcgraph`](ismbcgraph-functions.md)|**iswgraph**| -|**_istgraph_l**|**_isgraph_l**|[`_ismbcgraph_l`](ismbcgraph-functions.md)|**_iswgraph_l**| +|`_istgraph`|**`isgraph`**|[`_ismbcgraph`](ismbcgraph-functions.md)|**`iswgraph`**| +|**`_istgraph_l`**|**`_isgraph_l`**|[`_ismbcgraph_l`](ismbcgraph-functions.md)|**`_iswgraph_l`**| ## Remarks @@ -61,10 +61,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isgraph**|\| -|**iswgraph**|\ or \| -|**_isgraph_l**|\| -|**_iswgraph_l**|\ or \| +|**`isgraph`**|\| +|**`iswgraph`**|\ or \| +|**`_isgraph_l`**|\| +|**`_iswgraph_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/isinf.md b/docs/c-runtime-library/reference/isinf.md index 97d4596fa3c..9821ae201c6 100644 --- a/docs/c-runtime-library/reference/isinf.md +++ b/docs/c-runtime-library/reference/isinf.md @@ -29,17 +29,17 @@ 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 \| +|**`isinf`**|\|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md b/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md index ad00e8a4ab6..27826c091a0 100644 --- a/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md +++ b/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md @@ -31,30 +31,30 @@ Integer to test. ## 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 or 0 if it does not. 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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istleadbyte**|Always returns false|**_isleadbyte**|Always returns false| +|**`_istleadbyte`**|Always returns false|**`_isleadbyte`**|Always returns false| ## Requirements |Routine|Required header| |-------------|---------------------| -|**isleadbyte**|\| -|**_isleadbyte_l**|\| +|**`isleadbyte`**|\| +|**`_isleadbyte_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 c9219fb6b29..1c1c2afa9bf 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 @@ -43,18 +43,18 @@ Locale to use. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istlower**|**islower**|[`_ismbclower`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|**iswlower**| -|**_istlower_l**|`_islower _l`|[`_ismbclower_l`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|**_liswlower_l**| +|`_istlower`|**`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 @@ -64,10 +64,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**islower**|\| -|**iswlower**|\ or \| -|**_islower_l**|\| -|**_swlower_l**|\ or \| +|**`islower`**|\| +|**`iswlower`**|\ or \| +|**`_islower_l`**|\| +|**`_swlower_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md b/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md index ea51c937798..4592ecb4998 100644 --- a/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md +++ b/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md @@ -35,13 +35,13 @@ Locale to use. ## Return value -**_ismbbalnum** returns a nonzero value if the expression: +**`_ismbbalnum`** returns a nonzero value if the expression: `isalnum(c) || _ismbbkalnum(c)` is nonzero for *`c`*, or 0 if it is not. -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 @@ -51,8 +51,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbalnum**|\| -|**_ismbbalnum_l**|\| +|**`_ismbbalnum`**|\| +|**`_ismbbalnum_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md b/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md index 154778ffef1..9c64786b8db 100644 --- a/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md +++ b/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md @@ -35,11 +35,11 @@ Locale to use. ## Return value -**_ismbbalpha** returns a nonzero value if the expression: +**`_ismbbalpha`** returns a nonzero value if 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 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. ## Remarks @@ -49,8 +49,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbalpha**|\| -|**_ismbbalpha_l**|\| +|**`_ismbbalpha`**|\| +|**`_ismbbalpha_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md b/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md index d6c9e7b0a80..82283c65be4 100644 --- a/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md +++ b/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md @@ -37,7 +37,7 @@ Locale to use. ## 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](../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 @@ -47,8 +47,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbblank**|\| -|**_ismbbblank_l**|\| +|**`_ismbbblank`**|\| +|**`_ismbbblank_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md b/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md index 2be0ffa4cda..24bfd97a08a 100644 --- a/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md +++ b/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md @@ -40,7 +40,7 @@ Returns a nonzero value if 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](../locale.md). +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](../locale.md). ## Remarks @@ -50,8 +50,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbgraph**|\| -|**_ismbbgraph_l**|\| +|**`_ismbbgraph`**|\| +|**`_ismbbgraph_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md b/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md index 01a988126e1..8ebc145952f 100644 --- a/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md +++ b/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md @@ -36,7 +36,7 @@ Locale to use. ## 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](../locale.md). +**`_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](../locale.md). ## Remarks @@ -46,8 +46,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbkalnum**|\| -|**_ismbbkalnum_l**|\| +|**`_ismbbkalnum`**|\| +|**`_ismbbkalnum_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md b/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md index 396ab1da40e..1e324792bb6 100644 --- a/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md +++ b/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md @@ -36,7 +36,7 @@ Locale to use. ## 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](../locale.md). +**`_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](../locale.md). ## Remarks @@ -46,8 +46,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbkana**|\| -|**_ismbbkana_l**|\| +|**`_ismbbkana`**|\| +|**`_ismbbkana_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md b/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md index c14babf5459..3f7139e2f69 100644 --- a/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md +++ b/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md @@ -36,7 +36,7 @@ Locale to use. ## 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](../locale.md). +**`_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](../locale.md). ## Remarks @@ -46,8 +46,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbkprint**|\| -|**_ismbbkprint_l**|\| +|**`_ismbbkprint`**|\| +|**`_ismbbkprint_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md b/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md index 7c3aaa0ff14..ec6e953521b 100644 --- a/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md +++ b/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md @@ -36,7 +36,7 @@ Locale to use. ## 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](../locale.md). +**`_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](../locale.md). ## Remarks @@ -46,8 +46,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbkpunct**|\| -|**_ismbbkpunct_l**|\| +|**`_ismbbkpunct`**|\| +|**`_ismbbkpunct_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md b/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md index 03146e278da..0bc1a3ca649 100644 --- a/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md +++ b/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md @@ -42,26 +42,26 @@ Returns a nonzero value if the integer *`c`* is the first byte of a multibyte ch 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_istlead**|Always returns false|**_ismbblead**|Always returns false| +|`_istlead`|Always returns false|**`_ismbblead`**|Always returns false| ## Requirements |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_ismbblead**|\ or \|\,* \, \| -|**_ismbblead_l**|\ or \|\,* \, \| +|**`_ismbblead`**|\ or \|\,* \, \| +|**`_ismbblead_l`**|\ or \|\,* \, \| \* For manifest constants for the test conditions. diff --git a/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md b/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md index 22e6522bc9f..60dc5f18838 100644 --- a/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md +++ b/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md @@ -36,11 +36,11 @@ Locale to use. ## Return value -**_ismbbprint** returns a nonzero value if the expression: +**`_ismbbprint`** returns a nonzero value if 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](../locale.md). +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](../locale.md). ## Remarks @@ -50,8 +50,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbprint**|\| -|**_ismbbprint_l**|\| +|**`_ismbbprint`**|\| +|**`_ismbbprint_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md b/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md index 62c07a11ab0..48d95652e49 100644 --- a/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md +++ b/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md @@ -36,7 +36,7 @@ Locale to use. ## 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](../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 @@ -46,8 +46,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbbpunct**|\| -|**_ismbbpunct_l**|\| +|**`_ismbbpunct`**|\| +|**`_ismbbpunct_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md b/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md index 9d8e8267498..07d70f01939 100644 --- a/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md +++ b/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md @@ -36,11 +36,11 @@ The locale to use. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -48,8 +48,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_ismbbtrail**|\ or \|\,* \, \| -|**_ismbbtrail_l**|\ or \|\,* \, \| +|**`_ismbbtrail`**|\ or \|\,* \, \| +|**`_ismbbtrail_l`**|\ or \|\,* \, \| \* For manifest constants for the test conditions. diff --git a/docs/c-runtime-library/reference/ismbcalnum-functions.md b/docs/c-runtime-library/reference/ismbcalnum-functions.md index 7ab6b63bffb..bc9346a2929 100644 --- a/docs/c-runtime-library/reference/ismbcalnum-functions.md +++ b/docs/c-runtime-library/reference/ismbcalnum-functions.md @@ -59,19 +59,19 @@ Locale to use. ## 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 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. ## 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](../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.| +|**`_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 behavior, see [Global state in the CRT](../global-state.md). @@ -79,9 +79,9 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbcalnum**, **_ismbcalnum_l**|\| -|**_ismbcalpha**, **_ismbcalpha_l**|\| -|**_ismbcdigit**, **_ismbcdigit_l**|\| +|**`_ismbcalnum`**, **`_ismbcalnum_l`**|\| +|**`_ismbcalpha`**, **`_ismbcalpha_l`**|\| +|**`_ismbcdigit`**, **`_ismbcdigit_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ismbcgraph-functions.md b/docs/c-runtime-library/reference/ismbcgraph-functions.md index 0c3912f1f7d..786c219e909 100644 --- a/docs/c-runtime-library/reference/ismbcgraph-functions.md +++ b/docs/c-runtime-library/reference/ismbcgraph-functions.md @@ -67,9 +67,9 @@ Locale to use. ## 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, 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. -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). +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 @@ -77,11 +77,11 @@ 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.| +|**`_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 behavior, see [Global state in the CRT](../global-state.md). @@ -89,16 +89,16 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_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`**|\| For more compatibility information, see [Compatibility](../compatibility.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 74abab66eb2..70a0b80e802 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 @@ -46,20 +46,20 @@ Locale to use. ## 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 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. ## 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](../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.| +|**`_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** @@ -69,10 +69,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbchira**|\| -|**_ismbchira_l**|\| -|**_ismbckata**|\| -|**_ismbckata_l**|\| +|**`_ismbchira`**|\| +|**`_ismbchira_l`**|\| +|**`_ismbckata`**|\| +|**`_ismbckata_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 03da75dc0b0..a9994a3361a 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 @@ -53,22 +53,22 @@ Locale to use. ## 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 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. ## 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](../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](../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.| +|**`_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. @@ -80,12 +80,12 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbcl0**|\| -|**_ismbcl0_l**|\| -|**_ismbcl1**|\| -|**_ismbcl1_l**|\| -|**_ismbcl2**|\| -|**_ismbcl2_l**|\| +|**`_ismbcl0`**|\| +|**`_ismbcl0_l`**|\| +|**`_ismbcl1`**|\| +|**`_ismbcl1_l`**|\| +|**`_ismbcl2`**|\| +|**`_ismbcl2_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 f4fd9679145..26bcf6540b7 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 @@ -46,34 +46,34 @@ Locale to use. ## 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 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. ## 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](../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.| +|**`_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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_istlegal**|Always returns false|**_ismbclegal**|Always returns false.| -|**_istlegal_l**|Always returns false|**_ismbclegal_l**|Always returns false.| +|`_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**|\| +|**`_ismbclegal`**, **`_ismbclegal_l`**|\| +|**`_ismbcsymbol`**, **`_ismbcsymbol_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 03bca2952ff..b273e9791c2 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 @@ -46,20 +46,20 @@ Locale to use. ## 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 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. ## 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](../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.| +|**`_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 behavior, see [Global state in the CRT](../global-state.md). @@ -67,10 +67,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_ismbclower**|\| -|**_ismbclower_l**|\| -|**_ismbcupper**|\| -|**_ismbcupper_l**|\| +|**`_ismbclower`**|\| +|**`_ismbclower_l`**|\| +|**`_ismbcupper`**|\| +|**`_ismbcupper_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 e01e72eb8f0..63695d4e13c 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 @@ -53,13 +53,13 @@ The locale to use. ## 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](../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 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](../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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -67,10 +67,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_ismbslead**|\ or \|\,* \, \| -|**_ismbstrail**|\ or \|\,* \, \| -|**_ismbslead_l**|\ or \|\,* \, \| -|**_ismbstrail_l**|\ or \|\,* \, \| +|**`_ismbslead`**|\ or \|\,* \, \| +|**`_ismbstrail`**|\ or \|\,* \, \| +|**`_ismbslead_l`**|\ or \|\,* \, \| +|**`_ismbstrail_l`**|\ or \|\,* \, \| \* For manifest constants for the test conditions. diff --git a/docs/c-runtime-library/reference/isnan-isnan-isnanf.md b/docs/c-runtime-library/reference/isnan-isnan-isnanf.md index fff4022e6cf..58dc69eeaa6 100644 --- a/docs/c-runtime-library/reference/isnan-isnan-isnanf.md +++ b/docs/c-runtime-library/reference/isnan-isnan-isnanf.md @@ -42,24 +42,24 @@ The floating-point value to test. ## 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). -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 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. -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 \| +|**`isnan`**, **`_isnanf`**|\|\ or \| +|**`_isnan`**|\|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/isnormal.md b/docs/c-runtime-library/reference/isnormal.md index 5b60f8bb07f..63e769ab802 100644 --- a/docs/c-runtime-library/reference/isnormal.md +++ b/docs/c-runtime-library/reference/isnormal.md @@ -29,17 +29,17 @@ 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`* is neither zero, subnormal, infinite, nor 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 \| +|**`isnormal`**|\|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 cc4ac1f2994..e9d7c927be6 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 @@ -43,17 +43,17 @@ The locale to use. ## 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—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. -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](../locale.md). +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](../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`* 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. ### Generic-text routine mappings |TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_unicode defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_** **istprint**|**isprint**|[`_ismbcprint`](ismbcgraph-functions.md)|**iswprint**| +|`_istprint`|**`isprint`**|[`_ismbcprint`](ismbcgraph-functions.md)|**`iswprint`**| ## Remarks @@ -63,10 +63,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isprint**|\| -|**iswprint**|\ or \| -|**_isprint_l**|\| -|**_iswprint_l**|\ or \| +|**`isprint`**|\| +|**`iswprint`**|\ or \| +|**`_isprint_l`**|\| +|**`_iswprint_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 b6fc4867c53..7e9fc2c996b 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 @@ -43,17 +43,17 @@ The locale to use. ## 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 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. -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](../locale.md). +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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_** **istpunct**|**ispunct**|[`_ismbcpunct`](ismbcgraph-functions.md)|**iswpunct**| +|`_istpunct`|**`ispunct`**|[`_ismbcpunct`](ismbcgraph-functions.md)|**`iswpunct`**| ## Remarks @@ -63,10 +63,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**ispunct**|\| -|**iswpunct**|\ or \| -|**_ispunct_l**|\| -|**_iswpunct_l**|\ or \| +|**`ispunct`**|\| +|**`iswpunct`**|\ or \| +|**`_ispunct_l`**|\| +|**`_iswpunct_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 5da20a7a985..84bc59d6880 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 @@ -43,17 +43,17 @@ Locale to use. ## 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](../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; 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_** **istspace**|**isspace**|[`_ismbcspace`](ismbcgraph-functions.md)|**iswspace**| +|**_** **`istspace`**|**`isspace`**|[`_ismbcspace`](ismbcgraph-functions.md)|**`iswspace`**| ## Remarks @@ -63,10 +63,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isspace**|\| -|**iswspace**|\ or \| -|**_isspace_l**|\| -|**_iswspace_l**|\ or \| +|**`isspace`**|\| +|**`iswspace`**|\ or \| +|**`_isspace_l`**|\| +|**`_iswspace_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 504ebf0623d..e3b9241b25c 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 @@ -43,18 +43,18 @@ Locale to use. ## 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`* does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_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**| +|`_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 @@ -64,10 +64,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isupper**|\| -|**_isupper_l**|\| -|**iswupper**|\ or \| -|**_iswupper_l**|\| +|**`isupper`**|\| +|**`_isupper_l`**|\| +|**`iswupper`**|\ or \| +|**`_iswupper_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 308c11628c0..201a71e0fb1 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 @@ -43,19 +43,19 @@ Locale to use. ## 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`* does not 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 does not 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](../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`* 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_istxdigit**|**isxdigit**|**isxdigit**|**iswxdigit**| +|`_istxdigit`|**`isxdigit`**|**`isxdigit`**|**`iswxdigit`**| ## Remarks @@ -65,10 +65,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**isxdigit**|\| -|**iswxdigit**|\ or \| -|**_isxdigit_l**|\| -|**_iswxdigit_l**|\ or \| +|**`isxdigit`**|\| +|**`iswxdigit`**|\ or \| +|**`_isxdigit_l`**|\| +|**`_iswxdigit_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/itoa-itow.md b/docs/c-runtime-library/reference/itoa-itow.md index f70b9881ea8..13a7a74d17b 100644 --- a/docs/c-runtime-library/reference/itoa-itow.md +++ b/docs/c-runtime-library/reference/itoa-itow.md @@ -94,7 +94,7 @@ The **`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, and **`_ui64toa`** fu 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). -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 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: ```C By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -107,7 +107,7 @@ In C++, these functions have template overloads that invoke their safer counterp 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). -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 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: ```C #define _CRT_NONSTDC_NO_WARNINGS 1 @@ -123,11 +123,11 @@ To use one of these macros in a string conversion function, declare your convers |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`**| +|**`_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: @@ -163,7 +163,7 @@ These functions and macros are Microsoft-specific. For more compatibility inform ## 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 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 3feeb588a0d..ff453e10ba8 100644 --- a/docs/c-runtime-library/reference/itoa-s-itow-s.md +++ b/docs/c-runtime-library/reference/itoa-s-itow-s.md @@ -79,14 +79,14 @@ Zero if successful; an error code on failure. If any of the following 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`**| +|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`* 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. ## Remarks diff --git a/docs/c-runtime-library/reference/ldexp.md b/docs/c-runtime-library/reference/ldexp.md index ca343a0ed95..cca3aa42b08 100644 --- a/docs/c-runtime-library/reference/ldexp.md +++ b/docs/c-runtime-library/reference/ldexp.md @@ -51,13 +51,13 @@ Integer exponent. ## 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`](../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](../tgmath.md) for details. @@ -67,8 +67,8 @@ By default, this function's global state is scoped to the application. To change |Routine|C header|C++ header| |-------------|--------------|------------------| -|**ldexp**, **ldexpf**, **ldexpl**|\|\| -|**ldexp** macro | \ || +|**`ldexp`**, **`ldexpf`**, **`ldexpl`**|\|\| +|**`ldexp`** macro | \ || For compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lfind-s.md b/docs/c-runtime-library/reference/lfind-s.md index 17ab4b3668f..b8ee4584444 100644 --- a/docs/c-runtime-library/reference/lfind-s.md +++ b/docs/c-runtime-library/reference/lfind-s.md @@ -49,24 +49,24 @@ A pointer to an object that might be accessed in the comparison function. ## 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 is not found, **`_lfind_s`** 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**. +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 |*`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**| +|`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 *`size`* 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`** 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). -**_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 additional 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 behavior, see [Global state in the CRT](../global-state.md). @@ -74,7 +74,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_lfind_s**|\| +|**`_lfind_s`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lfind.md b/docs/c-runtime-library/reference/lfind.md index 0f3be949bd6..b10141085a8 100644 --- a/docs/c-runtime-library/reference/lfind.md +++ b/docs/c-runtime-library/reference/lfind.md @@ -45,13 +45,13 @@ Pointer to comparison routine. The first parameter is a pointer to key for searc ## 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 is not 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`** 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). -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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -59,7 +59,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_lfind**|\| +|**`_lfind`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md b/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md index c732611b57d..33981a31418 100644 --- a/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md +++ b/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md @@ -48,7 +48,7 @@ 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](../tgmath.md) for details. @@ -60,8 +60,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**lgamma**, **lgammaf**, **lgammal**|\|\| -|**lgamma** macro | \ || +|**`lgamma`**, **`lgammaf`**, **`lgammal`**|\|\| +|**`lgamma`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/localeconv.md b/docs/c-runtime-library/reference/localeconv.md index 40185a2861e..daac30fbe3c 100644 --- a/docs/c-runtime-library/reference/localeconv.md +++ b/docs/c-runtime-library/reference/localeconv.md @@ -22,11 +22,11 @@ struct lconv *localeconv( void ); ## Return value -**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 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 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. ## 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: +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| |-|-| @@ -49,37 +49,37 @@ n_sep_by_space|Set to 1 if currency symbol is separated by space from value for 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. +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 **`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: +The values of `grouping` and `mon_grouping` are interpreted according to the following rules: -- **CHAR_MAX** - Do not perform any further grouping. +- `CHAR_MAX` - Do not 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. -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. -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. @@ -97,7 +97,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**localeconv**|\| +|**`localeconv`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md b/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md index 12564be13c2..a94d0cbc3a0 100644 --- a/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md +++ b/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md @@ -29,7 +29,7 @@ Pointer to stored time. ## 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,7 +39,7 @@ 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 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. The fields of the structure type [`tm`](../standard-types.md) store the following values, each of which is an **`int`**: @@ -68,7 +68,7 @@ Both the 32-bit and 64-bit versions of [`gmtime`](gmtime-gmtime32-gmtime64.md), > [!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](../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 behavior, see [Global state in the CRT](../global-state.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 136371f0d21..60043da74a5 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 @@ -47,11 +47,11 @@ Zero if successful. The return value is an error code if there is a failure. Err |*`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| +|`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](../parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +In the case of the first two error conditions, 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 @@ -64,7 +64,7 @@ The **`localtime_s`** function converts a time stored as a [`time_t`](../standar **`_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 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. The fields of the structure type [`tm`](../standard-types.md) store the following values, each of which is an **`int`**. diff --git a/docs/c-runtime-library/reference/lock-file.md b/docs/c-runtime-library/reference/lock-file.md index fa89c2c30e4..67a4c2cebb7 100644 --- a/docs/c-runtime-library/reference/lock-file.md +++ b/docs/c-runtime-library/reference/lock-file.md @@ -12,7 +12,7 @@ ms.assetid: 75c7e0e6-efff-4747-b6ed-9bcf2b0894c3 --- # `_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 @@ -27,7 +27,7 @@ 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -35,7 +35,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_lock_file**|\| +|**`_lock_file`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/locking.md b/docs/c-runtime-library/reference/locking.md index e019dbb4d19..11ba2795dd2 100644 --- a/docs/c-runtime-library/reference/locking.md +++ b/docs/c-runtime-library/reference/locking.md @@ -37,32 +37,32 @@ Number of bytes to lock. ## Return value -**_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. +**`_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**. | +| `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`**. | 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 is possible to lock bytes past end of file. *`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. | +| `_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. | -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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -70,7 +70,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_locking**|\ and \|\| +|**`_locking`**|\ and \|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md b/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md index e2ca70e49fe..2df076fd109 100644 --- a/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md +++ b/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md @@ -60,13 +60,13 @@ Otherwise, may return one of the following values: |±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](../tgmath.md) for details. @@ -78,8 +78,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**log1p**, **log1pf**, **log1pl**|\|\| -|**log1p** macro | \ || +|**`log1p`**, **`log1pf`**, **`log1pl`**|\|\| +|**`log1p`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/log2-log2f-log2l.md b/docs/c-runtime-library/reference/log2-log2f-log2l.md index 089d9ac9c24..0d3e14d2b60 100644 --- a/docs/c-runtime-library/reference/log2-log2f-log2l.md +++ b/docs/c-runtime-library/reference/log2-log2f-log2l.md @@ -71,8 +71,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**log2**, **log2f**, **log2l**|\|\| -|**log2** macro | \ || +|**`log2`**, **`log2f`**, **`log2l`**|\|\| +|**`log2`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/longjmp.md b/docs/c-runtime-library/reference/longjmp.md index 4f34fb6e904..1681a60ccce 100644 --- a/docs/c-runtime-library/reference/longjmp.md +++ b/docs/c-runtime-library/reference/longjmp.md @@ -33,25 +33,25 @@ 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 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. -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 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. **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 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. -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. +- 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. -- 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). +- 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). -- Do not use **longjmp** to transfer control from a callback routine invoked directly or indirectly by Windows code. +- Do not 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** @@ -65,7 +65,7 @@ For more information, see [Using setjmp and longjmp](../../cpp/using-setjmp-long |Routine|Required header| |-------------|---------------------| -|**longjmp**|\| +|**`longjmp`**|\| For more compatibility information, see [Compatibility](../compatibility.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 af2a3b96cc3..7398a2ceb6d 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 @@ -71,15 +71,15 @@ 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).| +|*`x`* is outside the range of the return type

*`x`* = ±∞

*`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](../tgmath.md) for details. -If *`x`* does not represent the floating-point equivalent of an integral value, these functions raise **FE_INEXACT**. +If *`x`* does not 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. @@ -89,8 +89,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**lrint**, **lrintf**, **lrintl**, **llrint**, **llrintf**, **llrintl**|\|\| -|**lrint** macro | \ || +|**`lrint`**, **`lrintf`**, **`lrintl`**, **`llrint`**, **`llrintf`**, **`llrintl`**|\|\| +|**`lrint`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lrotl-lrotr.md b/docs/c-runtime-library/reference/lrotl-lrotr.md index b4a04e05dc9..e12210de0f1 100644 --- a/docs/c-runtime-library/reference/lrotl-lrotr.md +++ b/docs/c-runtime-library/reference/lrotl-lrotr.md @@ -12,7 +12,7 @@ ms.assetid: d42f295b-35f9-49d2-9ee4-c66896ffe68e --- # `_lrotl`, `_lrotr` -Rotates bits to the left (**_lrotl**) or right (**_lrotr**). +Rotates bits to the left (**`_lrotl`**) or right (**`_lrotr`**). ## Syntax @@ -35,13 +35,13 @@ 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**|\| +|**`_lrotl`**, **`_lrotr`**|\| For more compatibility information, see [Compatibility](../compatibility.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 a55aae946eb..89d0d8a6998 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 @@ -57,15 +57,15 @@ The floating-point value to round. ## 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**| +|± `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 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`**. 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. @@ -75,8 +75,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**lround**, **lroundf**, **lroundl**, **llround**, **llroundf**, **llroundl**|\| -|**lround** macro | \ | +|**`lround`**, **`lroundf`**, **`lroundl`**, **`llround`**, **`llroundf`**, **`llroundl`**|\| +|**`lround`** macro | \ | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lsearch-s.md b/docs/c-runtime-library/reference/lsearch-s.md index 7dc550a1906..bed9e24c966 100644 --- a/docs/c-runtime-library/reference/lsearch-s.md +++ b/docs/c-runtime-library/reference/lsearch-s.md @@ -49,26 +49,26 @@ A pointer to an object that might be accessed in the comparison function. ## 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`* is not 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](../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). +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 |*`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**| +|`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 *`size`* 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`** 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 *`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 additional 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 behavior, see [Global state in the CRT](../global-state.md). @@ -76,7 +76,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_lsearch_s**|\| +|**`_lsearch_s`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lsearch.md b/docs/c-runtime-library/reference/lsearch.md index fac300f1dc2..60ee493e5a1 100644 --- a/docs/c-runtime-library/reference/lsearch.md +++ b/docs/c-runtime-library/reference/lsearch.md @@ -45,15 +45,15 @@ Pointer to the comparison routine. The first parameter is a pointer to the key f ## 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 is not 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`** 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 *`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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -61,7 +61,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_lsearch**|\| +|**`_lsearch`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/lseek-lseeki64.md b/docs/c-runtime-library/reference/lseek-lseeki64.md index 82a7d96a6a7..10a7ce705a7 100644 --- a/docs/c-runtime-library/reference/lseek-lseeki64.md +++ b/docs/c-runtime-library/reference/lseek-lseeki64.md @@ -42,21 +42,21 @@ Initial position. ## 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](../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 [`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. | +| `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 behavior, see [Global state in the CRT](../global-state.md). @@ -64,8 +64,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_lseek**|\| -|**_lseeki64**|\| +|**`_lseek`**|\| +|**`_lseeki64`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 93eea77e7a9..a1938a86808 100644 --- a/docs/c-runtime-library/reference/makepath-s-wmakepath-s.md +++ b/docs/c-runtime-library/reference/makepath-s-wmakepath-s.md @@ -63,16 +63,16 @@ Size of the buffer in words. 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. +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. *`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. +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. *`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. +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. +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. ## Return value @@ -82,26 +82,26 @@ Zero if successful; an error code on failure. |*`path`*|*`sizeInWords`* / *`sizeInBytes`*|Return|Contents of *`path`*| |------------|------------------------------------|------------|------------------------| -|**NULL**|any|**EINVAL**|not modified| -|any|<= 0|**EINVAL**|not modified| +|`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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmakepath_s**|**_makepath_s**|**_makepath_s**|**_wmakepath_s**| +|`_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](../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](../secure-template-overloads.md). @@ -111,8 +111,8 @@ The debug library versions of these functions first fill the buffer with 0xFE. T |Routine|Required header| |-------------|---------------------| -|**_makepath_s**|\| -|**_wmakepath_s**|\ or \| +|**`_makepath_s`**|\| +|**`_wmakepath_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/makepath-wmakepath.md b/docs/c-runtime-library/reference/makepath-wmakepath.md index 04aeb233a1e..1769bc990f2 100644 --- a/docs/c-runtime-library/reference/makepath-wmakepath.md +++ b/docs/c-runtime-library/reference/makepath-wmakepath.md @@ -39,41 +39,41 @@ void _wmakepath( 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. +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. *`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. +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. *`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. +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. +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. ## 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`** 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). By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmakepath**|**_makepath**|**_makepath**|**_wmakepath**| +|`_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](../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 \| +|**`_makepath`**|\| +|**`_wmakepath`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/malloc-dbg.md b/docs/c-runtime-library/reference/malloc-dbg.md index 4bea14b74eb..2b51ff2650f 100644 --- a/docs/c-runtime-library/reference/malloc-dbg.md +++ b/docs/c-runtime-library/reference/malloc-dbg.md @@ -31,27 +31,27 @@ void *_malloc_dbg( Requested size of the memory block (in bytes). *`blockType`*\ -Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +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**. +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**. +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`](../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 -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`](../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) 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** 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 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** 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). +**`_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). @@ -59,7 +59,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_malloc_dbg**|\| +|**`_malloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). @@ -69,7 +69,7 @@ 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 diff --git a/docs/c-runtime-library/reference/malloc.md b/docs/c-runtime-library/reference/malloc.md index d83c04d96d1..19030c6e3b3 100644 --- a/docs/c-runtime-library/reference/malloc.md +++ b/docs/c-runtime-library/reference/malloc.md @@ -29,13 +29,13 @@ Bytes to allocate. ## 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 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. ## 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`](../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`**. diff --git a/docs/c-runtime-library/reference/malloca.md b/docs/c-runtime-library/reference/malloca.md index 093d376eb09..3037818cb6c 100644 --- a/docs/c-runtime-library/reference/malloca.md +++ b/docs/c-runtime-library/reference/malloca.md @@ -30,24 +30,24 @@ Bytes to be allocated from the stack. 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. -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). diff --git a/docs/c-runtime-library/reference/matherr.md b/docs/c-runtime-library/reference/matherr.md index 4103532d792..8d2e5fdd46f 100644 --- a/docs/c-runtime-library/reference/matherr.md +++ b/docs/c-runtime-library/reference/matherr.md @@ -28,8 +28,8 @@ Pointer to the structure containing error information. **`_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. +- 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). @@ -56,12 +56,12 @@ The **`type`** member specifies the type of math error. It's one of the followin |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.) | +| `_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`**. diff --git a/docs/c-runtime-library/reference/max.md b/docs/c-runtime-library/reference/max.md index 6e9dfd57efe..32061f5fa43 100644 --- a/docs/c-runtime-library/reference/max.md +++ b/docs/c-runtime-library/reference/max.md @@ -27,11 +27,11 @@ Values of any numeric type to be compared. ## 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++`. @@ -39,7 +39,7 @@ The argument returned is evaluated twice by the macro. This can lead to unexpect |Macro|Required header| |-------------|---------------------| -|**__max**|\| +|**`__max`**|\| ## Example diff --git a/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md b/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md index a81849c77a0..ff9815f23b2 100644 --- a/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md +++ b/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md @@ -39,15 +39,15 @@ Locale to use. ## 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](../locale.md). +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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -55,8 +55,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_mbbtombc**|\| -|**_mbbtombc_l**|\| +|**`_mbbtombc`**|\| +|**`_mbbtombc_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md b/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md index 226d6b8a3f3..f4d5bf5e19f 100644 --- a/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md +++ b/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md @@ -44,23 +44,23 @@ The locale to use. ## 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`*| +|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| +|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| ## 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](../locale.md). +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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -68,8 +68,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_mbbtype**|\|\*| -|**_mbbtype_l**|\|\*| +|**`_mbbtype`**|\|\*| +|**`_mbbtype_l`**|\|\*| \* For definitions of manifest constants that are used as return values. diff --git a/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md b/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md index db57bcaa08a..9458f200cc6 100644 --- a/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md +++ b/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md @@ -44,11 +44,11 @@ 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](../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](../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. @@ -56,17 +56,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tccpy**|Maps to macro or inline function|**_mbccpy**|Maps to macro or inline function| -|**_tccpy_l**|n/a|**_mbccpy_l**|n/a| +|`_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**|\| +|**`_mbccpy`**|\| +|**`_mbccpy_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 ae9be5b0f43..3c4ef523ef5 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 @@ -57,7 +57,7 @@ Copy destination. 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. +Filled with the number of bytes copied (1 or 2 if successful). Pass `NULL` if you don't care about the number. *`src`*\ Multibyte character to copy. @@ -67,26 +67,26 @@ Locale to use. ## 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](../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`* 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`. -**_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`** 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). -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**| +|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`*. -**_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](../secure-template-overloads.md). @@ -94,16 +94,16 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tccpy_s**|Maps to macro or inline function.|**_mbccpy_s**|Maps to macro or inline function.| +|`_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**|\| +|**`_mbccpy_s`**|\| +|**`_mbccpy_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 58a4f107250..1a06282bfd4 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 @@ -50,15 +50,15 @@ On Japanese locale, these functions return a converted character or return 0 if ## 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`](../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. Note that some code points in that range do not have a character assigned and so cannot 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 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](../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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -66,10 +66,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_mbcjistojms**|\| -|**_mbcjistojms_l**|\| -|**_mbcjmstojis**|\| -|**_mbcjmstojis_l**|\| +|**`_mbcjistojms`**|\| +|**`_mbcjistojms_l`**|\| +|**`_mbcjmstojis`**|\| +|**`_mbcjmstojis_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 c7ece699ce7..7b4cce64440 100644 --- a/docs/c-runtime-library/reference/mbclen-mblen-mblen-l.md +++ b/docs/c-runtime-library/reference/mbclen-mblen-mblen-l.md @@ -54,35 +54,35 @@ Locale to use. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tclen**|Maps to macro or inline function|**_mbclen**|Maps to macro or inline function| +|`_tclen`|Maps to macro or inline function|**`_mbclen`**|Maps to macro or inline function| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_mbclen**|\| -|**mblen**|\| -|**_mblen_l**|\| +|**`_mbclen`**|\| +|**`mblen`**|\| +|**`_mblen_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 ef46593aa6e..7ff93dde25c 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 @@ -50,16 +50,16 @@ Each of these functions returns the converted character *`c`*, if possible. Othe ## 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.| +|**`_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](../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 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 behavior, see [Global state in the CRT](../global-state.md). @@ -67,10 +67,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_mbctohira**|\| -|**_mbctohira_l**|\| -|**_mbctokata**|\| -|**_mbctokata_l**|\| +|**`_mbctohira`**|\| +|**`_mbctohira_l`**|\| +|**`_mbctokata`**|\| +|**`_mbctokata_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 13144ab2322..93decd73083 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 @@ -54,30 +54,30 @@ The functions test a character *`c`* and, if possible, apply one of the followin |Routines|Converts| |--------------|--------------| -|**_mbctolower**, **_mbctolower_l**|Uppercase character to lowercase character.| -|**_mbctoupper**, **_mbctoupper_l**|Lowercase character to uppercase character.| +|**`_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](../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 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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_totlower**|**tolower**|**_mbctolower**|**towlower**| -|**_totlower_l**|**_tolower_l**|**_mbctolower_l**|**_towlower_t**| -|**_totupper**|**toupper**|**_mbctoupper**|**towupper**| -|**_totupper_l**|**toupper_l**|**_mbctoupper_l**|**_towupper_l**| +|`_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**|\| +|**`_mbctolower`**, **`_mbctolower_l`**|\| +|**`_mbctoupper`**, **`_mbctoupper_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md b/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md index d3d8d62cf4c..6561d946b46 100644 --- a/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md +++ b/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md @@ -39,15 +39,15 @@ Locale to use. ## 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](../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 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -55,8 +55,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_mbctombb**|\| -|**_mbctombb_l**|\| +|**`_mbctombb`**|\| +|**`_mbctombb_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbrlen.md b/docs/c-runtime-library/reference/mbrlen.md index 5e8a452f385..24952512d4c 100644 --- a/docs/c-runtime-library/reference/mbrlen.md +++ b/docs/c-runtime-library/reference/mbrlen.md @@ -44,35 +44,35 @@ One of the following values: | 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. | +| (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. | ## 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 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 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. 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 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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|not applicable|not applicable|**mbrlen**|not applicable| +|not applicable|not applicable|**`mbrlen`**|not applicable| ## Requirements |Routine|Required header| |-------------|---------------------| -|**mbrlen**|\| +|**`mbrlen`**|\| 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 diff --git a/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md b/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md index 2e71d20aa22..aa7be3af7fc 100644 --- a/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md +++ b/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md @@ -44,7 +44,7 @@ Pointer to the UTF-8 multibyte character string to convert. 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. +Pointer to a `mbstate_t` conversion state object used to interpret the UTF-8 multibyte string to one or more output characters. ## Return value @@ -56,13 +56,13 @@ On success, returns the value of the first of these conditions that applies, giv |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.| +|-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.| ## 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. @@ -74,7 +74,7 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**mbrtoc16**, **mbrtoc32**|\|\| +|**`mbrtoc16`**, **`mbrtoc32`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbrtowc.md b/docs/c-runtime-library/reference/mbrtowc.md index a25bbd98d29..01c4dafe53c 100644 --- a/docs/c-runtime-library/reference/mbrtowc.md +++ b/docs/c-runtime-library/reference/mbrtowc.md @@ -37,7 +37,7 @@ Address of a sequence of bytes (a multibyte character). 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. +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. ## Return value @@ -50,7 +50,7 @@ The next *`count`* or fewer bytes complete the multibyte character that represen 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. (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 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. (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. @@ -65,7 +65,7 @@ In this case, the value of the arguments *`wchar`* and *`count`* 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. -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 behavior, see [Global state in the CRT](../global-state.md). @@ -192,7 +192,7 @@ WC String: AaBbCcÜïα∩≡xXyYzZ |Routine|Required header| |-------------|---------------------| -|**mbrtowc**|\| +|**`mbrtowc`**|\| ## See also diff --git a/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md b/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md index b183f6bf53d..47200637c3c 100644 --- a/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md +++ b/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md @@ -44,22 +44,22 @@ Locale to use. ## 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`*.| +|`_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](../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 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](../locale.md). -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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -67,8 +67,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_mbsbtype**|\|\*| -|**_mbsbtype_l**|\|\*| +|**`_mbsbtype`**|\|\*| +|**`_mbsbtype_l`**|\|\*| \* For manifest constants used as return values. diff --git a/docs/c-runtime-library/reference/mbsinit.md b/docs/c-runtime-library/reference/mbsinit.md index 3927e046b32..ffaee022226 100644 --- a/docs/c-runtime-library/reference/mbsinit.md +++ b/docs/c-runtime-library/reference/mbsinit.md @@ -29,11 +29,11 @@ A pointer to an [`mbstate_t`](../standard-types.md) variable. ## 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. diff --git a/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md b/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md index 4246c6f14c2..fd9b5fe1ad4 100644 --- a/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md +++ b/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md @@ -62,17 +62,17 @@ Locale to use. ## 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](../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 **`_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). -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**. +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](../secure-template-overloads.md). @@ -80,17 +80,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_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**| +|`_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**|\| +|**`_mbsnbcat`**|\| +|**`_mbsnbcat_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 3d679ebbe43..7c403e1479f 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 @@ -73,17 +73,17 @@ Zero if successful; otherwise, an error code. |**`dest`**|*`sizeInBytes`*|*`src`*|Return value| |------------|-------------------|-----------|------------------| -|**`NULL`**|any|any|**`EINVAL`**| -|Any|<= 0|any|**`EINVAL`**| -|Any|any|**`NULL`**|**`EINVAL`**| +|`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](../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](../locale.md). +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](../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](../secure-template-overloads.md). diff --git a/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md b/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md index 77617d3706e..c69f68aaac5 100644 --- a/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md +++ b/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md @@ -54,17 +54,17 @@ The return value indicates the ordinal relationship between the substrings of *` |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](../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`** is not 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](../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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -72,15 +72,15 @@ By default, this function's global state is scoped to the application. To change |Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| |---------------------|---------------------------------------|--------------------|-----------------------| -|**_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)| +|`_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**|\| +|**`_mbsnbcmp`**|\| +|**`_mbsnbcmp_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 978242dc154..ee8c4c776a3 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 @@ -65,37 +65,37 @@ The return value indicates the relation of the substrings of *`string1`* and *`s |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](../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](../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 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](../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, 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`. -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 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. -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](../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](../locale.md). By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_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)| +|`_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)| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_mbsnbcoll**|\| -|**_mbsnbcoll_l**|\| -|**_mbsnbicoll**|\| -|**_mbsnbicoll_l**|\| +|**`_mbsnbcoll`**|\| +|**`_mbsnbcoll_l`**|\| +|**`_mbsnbicoll`**|\| +|**`_mbsnbicoll_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md b/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md index 872b70272b1..4f9c6f105e5 100644 --- a/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md +++ b/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md @@ -62,15 +62,15 @@ Locale to use. ## 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](../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](../locale.md). +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](../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). @@ -81,17 +81,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_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**| +|`_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**|\| +|**`_mbsnbcpy`**|\| +|**`_mbsnbcpy_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 2f53db8471d..e6ad4b03acf 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 @@ -67,16 +67,16 @@ Locale to use. ## 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](../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](../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](../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](../secure-template-overloads.md). @@ -86,17 +86,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsncpy_s**|**_strncpy_s**|**_mbsnbcpy_s**|**_wcsncpy_s**| -|**_tcsncpy_s_l**|**_strncpy_s_l**|**_mbsnbcpy_s_l**|**_wcsncpy_s_l**| +|`_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**|\| +|**`_mbsnbcpy_s`**|\| +|**`_mbsnbcpy_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md b/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md index 92a11e92aad..9a74607e6c1 100644 --- a/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md +++ b/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md @@ -45,34 +45,34 @@ The return value indicates the relationship between the substrings. |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. -**_mbsnbicmp** recognizes multibyte-character sequences according to the [multibyte code page](../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 is not 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnicmp**|**_strnicmp**|**_mbsnbicmp**|**_wcsnicmp**| -|**_tcsnicmp_l**|**_strnicmp_l**|**_mbsnbicmp_l**|**_wcsnicmp_l**| +|`_tcsnicmp`|`_strnicmp`|**`_mbsnbicmp`**|`_wcsnicmp`| +|`_tcsnicmp_l`|`_strnicmp_l`|**`_mbsnbicmp_l`**|`_wcsnicmp_l`| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_mbsnbicmp**|\| +|**`_mbsnbicmp`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md b/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md index 95db2032f16..8676de00fc0 100644 --- a/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md +++ b/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md @@ -49,17 +49,17 @@ Locale to use. ## 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 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`*. -**_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](../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`* is not 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](../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 **`_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](../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). @@ -67,17 +67,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnset**|**_strnset**|**_mbsnbset**|**_wcsnset**| -|**_tcsnset_l**|**_strnset_l**|**_mbsnbset_l**|**_wcsnset_l**| +|`_tcsnset`|`_strnset`|**`_mbsnbset`**|`_wcsnset`| +|`_tcsnset_l`|`_strnset_l`|**`_mbsnbset_l`**|`_wcsnset_l`| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_mbsnbset**|\| -|**_mbsnbset_l**|\| +|**`_mbsnbset`**|\| +|**`_mbsnbset_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 27b24d32afe..5dcf22a336c 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 @@ -71,13 +71,13 @@ 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 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`*. -**_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](../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`* is not 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](../locale.md). +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](../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](../secure-template-overloads.md). @@ -87,17 +87,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnset_s**|**_strnset_s**|**_mbsnbset_s**|**_wcsnset_s**| -|**_tcsnset_s_l**|`_strnset_s _l`|**_mbsnbset_s_l**|**_wcsnset_s_l**| +|`_tcsnset_s`|`_strnset_s`|**`_mbsnbset_s`**|`_wcsnset_s`| +|`_tcsnset_s_l`|`_strnset_s _l`|**`_mbsnbset_s_l`**|`_wcsnset_s_l`| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_mbsnbset_s**|\| -|**_mbsnbset_s_l**|\| +|**`_mbsnbset_s`**|\| +|**`_mbsnbset_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mbsrtowcs-s.md b/docs/c-runtime-library/reference/mbsrtowcs-s.md index 3252e6bcb42..2769bb2cdf2 100644 --- a/docs/c-runtime-library/reference/mbsrtowcs-s.md +++ b/docs/c-runtime-library/reference/mbsrtowcs-s.md @@ -53,24 +53,24 @@ Indirect pointer to the location of the multibyte character string to be convert 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. +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. ## Return value Zero if conversion is successful, or an error code on failure. -|Error condition|Return value and **errno**| +|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**| +|*`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`| -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. +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 @@ -80,22 +80,22 @@ The **mbsrtowcs_s** function converts a string of multibyte characters indirectl The destination string *`wcstr`* is always null-terminated, even in the case of an error, unless *`wcstr`* is a null pointer. -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 *`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`* 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 *`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 *`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 is not 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 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 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. -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](../secure-template-overloads.md). @@ -103,13 +103,13 @@ By default, this function's global state is scoped to the application. To change ## 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 is not a null pointer. ## Requirements |Routine|Required header| |-------------|---------------------| -|**mbsrtowcs_s**|\| +|**`mbsrtowcs_s`**|\| ## See also diff --git a/docs/c-runtime-library/reference/mbsrtowcs.md b/docs/c-runtime-library/reference/mbsrtowcs.md index 80e5a8b4aed..bf59bd7c532 100644 --- a/docs/c-runtime-library/reference/mbsrtowcs.md +++ b/docs/c-runtime-library/reference/mbsrtowcs.md @@ -44,25 +44,25 @@ Indirect pointer to the location of the multibyte character string to convert. 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. +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. ## 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 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. -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 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`* does not have a corresponding multibyte character representation, a -1 is returned and the `errno` is set to `EILSEQ`. -If *`mbstr`* isa 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. +If *`mbstr`* isa 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](../secure-template-overloads.md). @@ -70,13 +70,13 @@ By default, this function's global state is scoped to the application. To change ## 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 is not a null pointer. ## Requirements |Routine|Required header| |-------------|---------------------| -|**mbsrtowcs**|\| +|**`mbsrtowcs`**|\| ## See also diff --git a/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md b/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md index 5b788b3d10e..9dd237cc202 100644 --- a/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md +++ b/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md @@ -58,7 +58,7 @@ The locale to use. ## 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 is not null-terminated. > [!IMPORTANT] > Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of multibyte characters to convert. @@ -67,9 +67,9 @@ 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](../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](../locale.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 d021de7c989..e9e25f95175 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 @@ -73,14 +73,14 @@ The locale to use. Zero if successful, an error code on failure. -|Error condition|Return value and **`errno`**| +|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`**| +|*`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`| -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. +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 @@ -96,9 +96,9 @@ The destination string is always null-terminated (even in the case of an error). 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`* 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`** 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. diff --git a/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md b/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md index 334fb649a74..af5ecfe502d 100644 --- a/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md +++ b/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md @@ -46,11 +46,11 @@ The locale to use. ## 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` 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. ## 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](../locale.md). +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](../locale.md). By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -58,8 +58,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**mbtowc**|\| -|**_mbtowc_l**|\| +|**`mbtowc`**|\| +|**`_mbtowc_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/memccpy.md b/docs/c-runtime-library/reference/memccpy.md index 1f7084ec2b9..3c461921bd7 100644 --- a/docs/c-runtime-library/reference/memccpy.md +++ b/docs/c-runtime-library/reference/memccpy.md @@ -41,11 +41,11 @@ Number of characters. ## 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`* is not 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 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. **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). @@ -53,7 +53,7 @@ The **_memccpy** function copies 0 or more characters of *`src`* to *`dest`*, ha |Routine|Required header| |-------------|---------------------| -|**_memccpy**|\ or \| +|**`_memccpy`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 9837569b238..c459c52d311 100644 --- a/docs/c-runtime-library/reference/memcpy-s-wmemcpy-s.md +++ b/docs/c-runtime-library/reference/memcpy-s-wmemcpy-s.md @@ -54,15 +54,15 @@ Zero if successful; an error code on failure. |*`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| +|`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. -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. +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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/memcpy-wmemcpy.md b/docs/c-runtime-library/reference/memcpy-wmemcpy.md index 2c2d0af8c40..a8808c30ee0 100644 --- a/docs/c-runtime-library/reference/memcpy-wmemcpy.md +++ b/docs/c-runtime-library/reference/memcpy-wmemcpy.md @@ -56,7 +56,7 @@ The value of *`dest`*. > > 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 example below: ```C #define _CRT_SECURE_DEPRECATE_MEMORY diff --git a/docs/c-runtime-library/reference/memicmp-memicmp-l.md b/docs/c-runtime-library/reference/memicmp-memicmp-l.md index 71601b761a3..faad6bdc6d4 100644 --- a/docs/c-runtime-library/reference/memicmp-memicmp-l.md +++ b/docs/c-runtime-library/reference/memicmp-memicmp-l.md @@ -53,15 +53,15 @@ The return value indicates the relationship between the buffers. |< 0|*`buffer1`* less than *`buffer2`*.| |0|*`buffer1`* identical to *`buffer2`*.| |> 0|*`buffer1`* greater than *`buffer2`*.| -|**_NLSCMPERROR**|An error occurred.| +|`_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 is not case-sensitive. -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**. +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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -69,8 +69,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_memicmp**|\ or \| -|**_memicmp_l**|\ or \| +|**`_memicmp`**|\ or \| +|**`_memicmp_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). 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 5363742d483..a05456c8df7 100644 --- a/docs/c-runtime-library/reference/memmove-s-wmemmove-s.md +++ b/docs/c-runtime-library/reference/memmove-s-wmemmove-s.md @@ -43,7 +43,7 @@ Size of the destination buffer. Source object. *`count`*\ -Number of bytes (**memmove_s**) or characters (**wmemmove_s**) to copy. +Number of bytes (**`memmove_s`**) or characters (**`wmemmove_s`**) to copy. ## Return value @@ -53,15 +53,15 @@ Zero if successful; an error code on failure |*`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| +|`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 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. -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**. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -69,8 +69,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**memmove_s**|\| -|**wmemmove_s**|\| +|**`memmove_s`**|\| +|**`wmemmove_s`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/memmove-wmemmove.md b/docs/c-runtime-library/reference/memmove-wmemmove.md index 7779da2318a..9a7a93e3d97 100644 --- a/docs/c-runtime-library/reference/memmove-wmemmove.md +++ b/docs/c-runtime-library/reference/memmove-wmemmove.md @@ -49,7 +49,7 @@ Copies *`count`* bytes (**`memmove`**) or characters (**`wmemmove`**) from *`src **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). -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 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: ```C #define _CRT_SECURE_DEPRECATE_MEMORY diff --git a/docs/c-runtime-library/reference/min.md b/docs/c-runtime-library/reference/min.md index 0696660905a..95ac58d8fa1 100644 --- a/docs/c-runtime-library/reference/min.md +++ b/docs/c-runtime-library/reference/min.md @@ -31,7 +31,7 @@ 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++`. @@ -39,7 +39,7 @@ The argument returned is evaluated twice by the macro. This can lead to unexpect |Routine|Required header| |-------------|---------------------| -|**__min**|\| +|**`__min`**|\| ## Example diff --git a/docs/c-runtime-library/reference/mkdir-wmkdir.md b/docs/c-runtime-library/reference/mkdir-wmkdir.md index 79c428cc5c9..bde4c538a4c 100644 --- a/docs/c-runtime-library/reference/mkdir-wmkdir.md +++ b/docs/c-runtime-library/reference/mkdir-wmkdir.md @@ -33,11 +33,11 @@ Path for a new directory. ## 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 was not created because *`dirname`* is the name of an existing file, directory, or device. -**`ENOENT`** Path was not found. +`ENOENT` Path was not found. 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). diff --git a/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md b/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md index ed74d778c28..3ce7030216e 100644 --- a/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md +++ b/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md @@ -40,11 +40,11 @@ A quantity of type **`__time32_t`** or **`__time64_t`** representing the number The **`_mkgmtime32`** and **`_mkgmtime64`** functions convert a UTC time to a **`__time32_t`** or **`__time64_t`** type representing the time in UTC. To convert a local time to UTC time, use **`mktime`**, **`_mktime32`**, and **`_mktime64`** instead. -**`_mkgmtime`** is an inline function that evaluates to **`_mkgmtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. We don't recommend it, because your application might fail after January 18, 2038, the maximum range of a 32-bit **`time_t`**. It's not allowed at all on 64-bit platforms. +**`_mkgmtime`** is an inline function that evaluates to **`_mkgmtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`. We don't recommend it, because your application might fail after January 18, 2038, the maximum range of a 32-bit **`time_t`**. It's not allowed at all on 64-bit platforms. The time structure passed in is changed as follows, in the same way as it's changed by the **`_mktime`** functions: the **`tm_wday`** and **`tm_yday`** fields are set to new values based on the values of **`tm_mday`** and **`tm_year`**. Because the time is assumed to be UTC, the **`tm_isdst`** field is ignored. -The range of the **`_mkgmtime32`** function is from midnight, January 1, 1970, UTC to 23:59:59 January 18, 2038, UTC. The range of **`_mkgmtime64`** is from midnight, January 1, 1970, UTC to 23:59:59, December 31, 3000, UTC. An out-of-range date results in a return value of -1. The range of **`_mkgmtime`** depends on whether **`_USE_32BIT_TIME_T`** is defined. When it's not defined, which is the default, the range is the same as **`_mkgmtime64`**. Otherwise, the range is limited to the 32-bit range of **`_mkgmtime32`**. +The range of the **`_mkgmtime32`** function is from midnight, January 1, 1970, UTC to 23:59:59 January 18, 2038, UTC. The range of **`_mkgmtime64`** is from midnight, January 1, 1970, UTC to 23:59:59, December 31, 3000, UTC. An out-of-range date results in a return value of -1. The range of **`_mkgmtime`** depends on whether `_USE_32BIT_TIME_T` is defined. When it's not defined, which is the default, the range is the same as **`_mkgmtime64`**. Otherwise, the range is limited to the 32-bit range of **`_mkgmtime32`**. Both **`gmtime`** and **`localtime`** use a common static buffer for the conversion. If you supply this buffer to **`_mkgmtime`**, the previous contents are destroyed. 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 7560bb533a6..c5124c8ba94 100644 --- a/docs/c-runtime-library/reference/mktemp-s-wmktemp-s.md +++ b/docs/c-runtime-library/reference/mktemp-s-wmktemp-s.md @@ -41,7 +41,7 @@ errno_t _wmktemp_s( File name pattern. *`sizeInChars`*\ -Size of the buffer in single-byte characters in **_mktemp_s**; wide characters in **_wmktemp_s**, including the null terminator. +Size of the buffer in single-byte characters in **`_mktemp_s`**; wide characters in **`_wmktemp_s`**, including the null terminator. ## Return value @@ -51,15 +51,15 @@ Both of these functions return zero on success; an error code on failure. |*`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| +|`NULL`|any|`EINVAL`|`NULL`| +|Incorrect format (see Remarks section for correct format)|any|`EINVAL`|empty string| +|any|<= number of X's|`EINVAL`|empty string| -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**. +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`** does not 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). @@ -67,29 +67,29 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmktemp_s**|**_mktemp_s**|**_mktemp_s**|**_wmktemp_s**| +|`_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 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. -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: -> **fnb12345** +> **`fnb12345`** If FNA12345 does not 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](../secure-template-overloads.md). @@ -97,8 +97,8 @@ In C++, using these functions is simplified by template overloads; the overloads |Routine|Required header| |-------------|---------------------| -|**_mktemp_s**|\| -|**_wmktemp_s**|\ or \| +|**`_mktemp_s`**|\| +|**`_wmktemp_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mktemp-wmktemp.md b/docs/c-runtime-library/reference/mktemp-wmktemp.md index 5a613f148cb..9bdd1d51e51 100644 --- a/docs/c-runtime-library/reference/mktemp-wmktemp.md +++ b/docs/c-runtime-library/reference/mktemp-wmktemp.md @@ -40,41 +40,41 @@ File name pattern. ## 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`** does not handle multibyte-character strings. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmktemp**|**_mktemp**|**_mktemp**|**_wmktemp**| +|`_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 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. -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: -> **fnb12345** +> **`fnb12345`** If FNA12345 does not 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 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`. 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). @@ -82,8 +82,8 @@ In C++, these functions have template overloads that invoke the newer, secure co |Routine|Required header| |-------------|---------------------| -|**_mktemp**|\| -|**_wmktemp**|\ or \| +|**`_mktemp`**|\| +|**`_wmktemp`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md b/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md index 92553c4fbaa..a925f191ddb 100644 --- a/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md +++ b/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md @@ -42,7 +42,7 @@ 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. @@ -58,7 +58,7 @@ The C run-time library will determine the daylight savings time behavior from th 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. -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`**. +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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/modf-modff-modfl.md b/docs/c-runtime-library/reference/modf-modff-modfl.md index 89ac8153132..e0632dc9f98 100644 --- a/docs/c-runtime-library/reference/modf-modff-modfl.md +++ b/docs/c-runtime-library/reference/modf-modff-modfl.md @@ -40,9 +40,9 @@ This function returns the signed fractional portion of *`x`*. There's no error r ## 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. diff --git a/docs/c-runtime-library/reference/msize-dbg.md b/docs/c-runtime-library/reference/msize-dbg.md index ad6ed6e8522..20a62eefbf3 100644 --- a/docs/c-runtime-library/reference/msize-dbg.md +++ b/docs/c-runtime-library/reference/msize-dbg.md @@ -29,25 +29,25 @@ size_t _msize_dbg( Pointer to the memory block for which to determine the size. *`blockType`*\ -Type of the specified memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +Type of the specified memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. ## 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`](../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) 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. 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). -This function validates its parameter. If *`memblock`* is a null pointer, **_msize** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer, **`_msize_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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**_msize_dbg**|\| +|**`_msize_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/msize.md b/docs/c-runtime-library/reference/msize.md index 37b4c72df75..b7822a5406b 100644 --- a/docs/c-runtime-library/reference/msize.md +++ b/docs/c-runtime-library/reference/msize.md @@ -36,7 +36,7 @@ The **`_msize`** function returns the size, in bytes, of the memory block alloca 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). -This function validates its parameter. If *`memblock`* is a `NULL` pointer, **`_msize`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets **`errno`** to **`EINVAL`** and returns -1. +This function validates its parameter. If *`memblock`* is a `NULL` pointer, **`_msize`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/nan-nanf-nanl.md b/docs/c-runtime-library/reference/nan-nanf-nanl.md index 4d20850607f..130e435c262 100644 --- a/docs/c-runtime-library/reference/nan-nanf-nanl.md +++ b/docs/c-runtime-library/reference/nan-nanf-nanl.md @@ -29,11 +29,11 @@ A string 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 behavior, see [Global state in the CRT](../global-state.md). @@ -41,7 +41,7 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**nan**, **nanf**, **nanl**|\|\ or \| +|**`nan`**, **`nanf`**, **`nanl`**|\|\ or \| ## See also diff --git a/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md b/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md index ca81425243c..61123bc3085 100644 --- a/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md +++ b/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md @@ -41,7 +41,7 @@ If successful, returns *`x`*, rounded to the nearest integer, using the current |*`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 are not reported through [`_matherr`](matherr.md); specifically, this function does not report any `FE_INEXACT` exceptions. ## Remarks @@ -49,7 +49,7 @@ The primary difference between this function and [`rint`](rint-rintf-rintl.md) i 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](../tgmath.md) for details. @@ -59,8 +59,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**nearbyint**, **nearbyintf**, **nearbyintl**|\|\ or \| -|**nearbyint** macro | \ || +|**`nearbyint`**, **`nearbyintf`**, **`nearbyintl`**|\|\ or \| +|**`nearbyint`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/nextafter-functions.md b/docs/c-runtime-library/reference/nextafter-functions.md index 62f12ff5ea3..ddebd13bd25 100644 --- a/docs/c-runtime-library/reference/nextafter-functions.md +++ b/docs/c-runtime-library/reference/nextafter-functions.md @@ -48,7 +48,7 @@ The floating-point value to go towards. ## 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`* 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`. ## Remarks @@ -58,7 +58,7 @@ Because C++ allows overloading, if you include `` you can call overloads 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](../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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/norm-normf-norml1.md b/docs/c-runtime-library/reference/norm-normf-norml1.md index 4a62463c00e..04ef39f1a9f 100644 --- a/docs/c-runtime-library/reference/norm-normf-norml1.md +++ b/docs/c-runtime-library/reference/norm-normf-norml1.md @@ -38,15 +38,15 @@ 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**|\|\| +|**`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](../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 diff --git a/docs/c-runtime-library/reference/offsetof-macro.md b/docs/c-runtime-library/reference/offsetof-macro.md index a9861045ab5..79a156c1350 100644 --- a/docs/c-runtime-library/reference/offsetof-macro.md +++ b/docs/c-runtime-library/reference/offsetof-macro.md @@ -32,20 +32,20 @@ Name of the member in the parent data structure for which to determine the offse ## 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 is 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**|\| +|**`offsetof`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/onexit-onexit-m.md b/docs/c-runtime-library/reference/onexit-onexit-m.md index d30dcd6daaa..8b094c1a998 100644 --- a/docs/c-runtime-library/reference/onexit-onexit-m.md +++ b/docs/c-runtime-library/reference/onexit-onexit-m.md @@ -32,21 +32,21 @@ Pointer to a function to be called at exit. ## 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 is 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`** cannot 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 on a DLL's unloading 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**|\| +|**`_onexit`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/open-osfhandle.md b/docs/c-runtime-library/reference/open-osfhandle.md index 553f368be3a..9a2ce74d58b 100644 --- a/docs/c-runtime-library/reference/open-osfhandle.md +++ b/docs/c-runtime-library/reference/open-osfhandle.md @@ -36,18 +36,18 @@ If successful, **`_open_osfhandle`** returns a C run-time file descriptor. Other ## 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 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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/open-wopen.md b/docs/c-runtime-library/reference/open-wopen.md index a85a52217ee..487b3a3f0b4 100644 --- a/docs/c-runtime-library/reference/open-wopen.md +++ b/docs/c-runtime-library/reference/open-wopen.md @@ -42,15 +42,15 @@ 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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -68,45 +68,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](../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. - -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. - -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. +| `_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](../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. + +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. + +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](../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](../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 diff --git a/docs/c-runtime-library/reference/pclose.md b/docs/c-runtime-library/reference/pclose.md index e1d50e8b32e..fe75d4d9494 100644 --- a/docs/c-runtime-library/reference/pclose.md +++ b/docs/c-runtime-library/reference/pclose.md @@ -28,17 +28,17 @@ FILE *stream ### Parameters *`stream`*\ -Return value from the previous call to **_popen**. +Return value from the previous call to `_popen`. ## 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 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. 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 behavior, see [Global state in the CRT](../global-state.md). @@ -46,7 +46,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_pclose**|\| +|**`_pclose`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/perror-wperror.md b/docs/c-runtime-library/reference/perror-wperror.md index a2b888c980b..fb0a52c4a2f 100644 --- a/docs/c-runtime-library/reference/perror-wperror.md +++ b/docs/c-runtime-library/reference/perror-wperror.md @@ -32,30 +32,30 @@ 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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tperror**|**perror**|**perror**|**_wperror**| +|`_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`](../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. +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 with 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 [`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. +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 \| +|**`perror`**|\ or \| +|**`_wperror`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/pipe.md b/docs/c-runtime-library/reference/pipe.md index ca2670672ee..ca83ae6a7a4 100644 --- a/docs/c-runtime-library/reference/pipe.md +++ b/docs/c-runtime-library/reference/pipe.md @@ -39,13 +39,13 @@ File mode. ## 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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -55,15 +55,15 @@ The **`_pipe`** function creates a *pipe*, which is an artificial I/O channel th **`_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 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`](../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 a text translation, and the constant `_O_BINARY` specifies binary translation. (See [`fopen`, `_wfopen`](fopen-wfopen.md) for a description of text and binary modes.) If the *`textmode`* argument is 0, **`_pipe`** uses the default translation mode that's specified by the default-mode variable [`_fmode`](../fmode.md). 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. 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. 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. @@ -75,9 +75,9 @@ By default, this function's global state is scoped to the application. To change |-------------|---------------------|---------------------| |**`_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](../compatibility.md). diff --git a/docs/c-runtime-library/reference/popen-wpopen.md b/docs/c-runtime-library/reference/popen-wpopen.md index b2a81ce81f1..dc463bdb2a7 100644 --- a/docs/c-runtime-library/reference/popen-wpopen.md +++ b/docs/c-runtime-library/reference/popen-wpopen.md @@ -41,7 +41,7 @@ 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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.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 aa10d80b4a3..1792bfa954b 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 @@ -53,34 +53,34 @@ 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](../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](../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. -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**. +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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \| +|**`_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 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 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). 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 37f76412650..bdd7ebf297a 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 @@ -49,13 +49,13 @@ The locale to use. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../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. 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 2abf47a6f4e..4eead53e7cc 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 @@ -55,11 +55,11 @@ 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../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. diff --git a/docs/c-runtime-library/reference/purecall.md b/docs/c-runtime-library/reference/purecall.md index 99f7944d0e2..cf9313cb8ac 100644 --- a/docs/c-runtime-library/reference/purecall.md +++ b/docs/c-runtime-library/reference/purecall.md @@ -22,15 +22,15 @@ 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 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. -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 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. By default, 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 does not have a header declaration. The `_purecall_handler` typedef is defined in \. ## See also 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 1e200a5abd0..40e178b7f08 100644 --- a/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md +++ b/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md @@ -33,7 +33,7 @@ wint_t _putwc_nolock( Character to be written. *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## Return value @@ -41,26 +41,26 @@ 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 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. -**_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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttc_nolock**|**_putc_nolock**|**_putc_nolock**|**_putwc_nolock**| +|`_puttc_nolock`|**`_putc_nolock`**|**`_putc_nolock`**|**`_putwc_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_putc_nolock**|\| -|**_putwc_nolock**|\ or \| +|**`_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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Libraries diff --git a/docs/c-runtime-library/reference/putc-putwc.md b/docs/c-runtime-library/reference/putc-putwc.md index dcc4bd14649..0ae187e61ba 100644 --- a/docs/c-runtime-library/reference/putc-putwc.md +++ b/docs/c-runtime-library/reference/putc-putwc.md @@ -33,36 +33,36 @@ wint_t putwc( Character to be written. *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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](../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`. 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 [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 **`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 aren't 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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_puttc**|**putc**|**putc**|**putwc**| +|`_puttc`|**`putc`**|**`putc`**|**`putwc`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**putc**|\| -|**putwc**|\ or \| +|**`putc`**|\| +|**`putwc`**|\ 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](../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 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 7951b64c7dc..dd7d2ced817 100644 --- a/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md +++ b/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md @@ -35,26 +35,26 @@ Character to be output. ## 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttch_nolock**|**_putch_nolock**|**_putch_nolock**|**_putwch_nolock**| +|`_puttch_nolock`|**`_putch_nolock`**|**`_putch_nolock`**|**`_putwch_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_putch_nolock**|\| -|**_putwch_nolock**|\| +|**`_putch_nolock`**|\| +|**`_putwch_nolock`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/putch-putwch.md b/docs/c-runtime-library/reference/putch-putwch.md index 1c96c7a5c99..2e30d5f23c7 100644 --- a/docs/c-runtime-library/reference/putch-putwch.md +++ b/docs/c-runtime-library/reference/putch-putwch.md @@ -36,28 +36,28 @@ Character to be output. ## 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 are not 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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttch**|**_putch**|**_putch**|**_putwch**| +|`_puttch`|**`_putch`**|**`_putch`**|**`_putwch`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_putch**|\| -|**_putwch**|\| +|**`_putch`**|\| +|**`_putwch`**|\| For more compatibility information, see [Compatibility](../compatibility.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 254d6a05d8b..7f044ae5697 100644 --- a/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md +++ b/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md @@ -12,7 +12,7 @@ ms.assetid: 9ac68092-bfc3-4352-b486-c3e780220575 --- # `_putchar_nolock`, `_putwchar_nolock` -Writes a character to **stdout** without locking the thread. +Writes a character to `stdout` without locking the thread. ## Syntax @@ -36,22 +36,22 @@ 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 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. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttchar_nolock**|**_putchar_nolock**|**_putchar_nolock**|**_putwchar_nolock**| +|`_puttchar_nolock`|**`_putchar_nolock`**|**`_putchar_nolock`**|**`_putwchar_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_putchar_nolock**|\| -|**_putwchar_nolock**|\ or \| +|**`_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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Libraries diff --git a/docs/c-runtime-library/reference/putchar-putwchar.md b/docs/c-runtime-library/reference/putchar-putwchar.md index a85f0c3ab9d..2c4b8d3c83f 100644 --- a/docs/c-runtime-library/reference/putchar-putwchar.md +++ b/docs/c-runtime-library/reference/putchar-putwchar.md @@ -12,7 +12,7 @@ ms.assetid: 93657c7f-cca1-4032-8e3a-cd6ab6193748 --- # `putchar`, `putwchar` -Writes a character to **stdout**. +Writes a character to `stdout`. ## Syntax @@ -32,32 +32,32 @@ Character to be written. ## 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](../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`. 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 [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 `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 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. +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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_puttchar**|**putchar**|**putchar**|**putwchar**| +|`_puttchar`|**`putchar`**|**`putchar`**|**`putwchar`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**putchar**|\| -|**putwchar**|\ or \| +|**`putchar`**|\| +|**`putwchar`**|\ 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](../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 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 2b50e718996..7b30b5ed5fc 100644 --- a/docs/c-runtime-library/reference/putenv-s-wputenv-s.md +++ b/docs/c-runtime-library/reference/putenv-s-wputenv-s.md @@ -45,10 +45,10 @@ Returns 0 if successful, or an error code. |*`varname`*|*`value_string`*|Return value| |------------|-------------|------------------| -|**`NULL`**|any|**`EINVAL`**| -|any|**`NULL`**|**`EINVAL`**| +|`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](../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 @@ -58,7 +58,7 @@ 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| +|`TCHAR.H` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_tputenv_s`**|**`_putenv_s`**|**`_putenv_s`**|**`_wputenv_s`**| diff --git a/docs/c-runtime-library/reference/puts-putws.md b/docs/c-runtime-library/reference/puts-putws.md index ff9287520a4..3d547bf3b51 100644 --- a/docs/c-runtime-library/reference/puts-putws.md +++ b/docs/c-runtime-library/reference/puts-putws.md @@ -12,7 +12,7 @@ ms.assetid: 32dada12-ed45-40ac-be06-3feeced9ecd6 --- # `puts`, `_putws` -Writes a string to **stdout**. +Writes a string to `stdout`. ## Syntax @@ -32,34 +32,34 @@ Output string. ## 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](../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 [`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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_putts**|**puts**|**puts**|**_putws**| +|`_putts`|**`puts`**|**`puts`**|**`_putws`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**puts**|\| -|**_putws**|\| +|**`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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Libraries diff --git a/docs/c-runtime-library/reference/putw.md b/docs/c-runtime-library/reference/putw.md index 43380cccb6d..9c4de6c3801 100644 --- a/docs/c-runtime-library/reference/putw.md +++ b/docs/c-runtime-library/reference/putw.md @@ -29,17 +29,17 @@ int _putw( Binary integer to be output. *`stream`*\ -Pointer to the **FILE** structure. +Pointer to the `FILE` structure. ## 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](../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 [`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`** 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -47,7 +47,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_putw**|\| +|**`_putw`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/qsort-s.md b/docs/c-runtime-library/reference/qsort-s.md index 3791736b376..3b9c80dbcc2 100644 --- a/docs/c-runtime-library/reference/qsort-s.md +++ b/docs/c-runtime-library/reference/qsort-s.md @@ -45,7 +45,7 @@ A pointer to a context, which can be any object that the *`compare`* routine nee ## 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 ); @@ -55,13 +55,13 @@ The routine must compare the elements and then return one of the following value |Return value|Description| |------------------|-----------------| -|< 0|**elem1** less than **elem2**| -|0|**elem1** equivalent to **elem2**| -|> 0|**elem1** greater than **elem2**| +|< 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](../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). +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 behavior, see [Global state in the CRT](../global-state.md). @@ -69,18 +69,18 @@ By default, this function's global state is scoped to the application. To change |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**| +|`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`. 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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**qsort_s**|\ and \| +|**`qsort_s`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.md). @@ -88,7 +88,7 @@ For more compatibility information, see [Compatibility](../compatibility.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 diff --git a/docs/c-runtime-library/reference/qsort.md b/docs/c-runtime-library/reference/qsort.md index 61f9cf7f278..1d74b1ae215 100644 --- a/docs/c-runtime-library/reference/qsort.md +++ b/docs/c-runtime-library/reference/qsort.md @@ -58,7 +58,7 @@ The routine compares the elements and returns one of the following values. 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](../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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/query-new-handler.md b/docs/c-runtime-library/reference/query-new-handler.md index 96d8eba4540..8eaeda73dbe 100644 --- a/docs/c-runtime-library/reference/query-new-handler.md +++ b/docs/c-runtime-library/reference/query-new-handler.md @@ -24,17 +24,17 @@ _PNH _query_new_handler( ## 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**|\| +|**`_query_new_handler`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/query-new-mode.md b/docs/c-runtime-library/reference/query-new-mode.md index d17b83650e2..1c912f2c0eb 100644 --- a/docs/c-runtime-library/reference/query-new-mode.md +++ b/docs/c-runtime-library/reference/query-new-mode.md @@ -12,7 +12,7 @@ ms.assetid: e185c5f9-b73b-4257-8eff-b47648374768 --- # `_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 @@ -24,17 +24,17 @@ int _query_new_mode( ## 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 does not. ## 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` 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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**_query_new_mode**|\| +|**`_query_new_mode`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/quick-exit1.md b/docs/c-runtime-library/reference/quick-exit1.md index 8a3d984aa05..9b9d85a278a 100644 --- a/docs/c-runtime-library/reference/quick-exit1.md +++ b/docs/c-runtime-library/reference/quick-exit1.md @@ -29,21 +29,21 @@ The status code to return to the host environment. ## Return value -The **quick_exit** function cannot return to its caller. +The **`quick_exit`** function cannot 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 \| +|**`quick_exit`**|\ or \| For more information about compatibility, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/raise.md b/docs/c-runtime-library/reference/raise.md index 35dcc05f2b4..dd60c072d96 100644 --- a/docs/c-runtime-library/reference/raise.md +++ b/docs/c-runtime-library/reference/raise.md @@ -31,22 +31,22 @@ Signal to be raised. ## 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| +|`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](../parameter-validation.md). If not handled, the function sets **errno** to **EINVAL** and returns a nonzero value. +If the argument is not 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 behavior, see [Global state in the CRT](../global-state.md). @@ -54,7 +54,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**raise**|\| +|**`raise`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rand-s.md b/docs/c-runtime-library/reference/rand-s.md index bb1a6c1766b..6e091d8eb45 100644 --- a/docs/c-runtime-library/reference/rand-s.md +++ b/docs/c-runtime-library/reference/rand-s.md @@ -26,13 +26,13 @@ A pointer to an integer to hold the generated 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](../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 **`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: By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/rand.md b/docs/c-runtime-library/reference/rand.md index b08c81a4e81..bde561a4d5d 100644 --- a/docs/c-runtime-library/reference/rand.md +++ b/docs/c-runtime-library/reference/rand.md @@ -25,7 +25,7 @@ int rand(void); ## 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). diff --git a/docs/c-runtime-library/reference/read.md b/docs/c-runtime-library/reference/read.md index a6cee14705b..7ff1e9c921a 100644 --- a/docs/c-runtime-library/reference/read.md +++ b/docs/c-runtime-library/reference/read.md @@ -38,9 +38,9 @@ Maximum number of bytes to read. **`_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. -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](../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`* 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/realloc-dbg.md b/docs/c-runtime-library/reference/realloc-dbg.md index e26ce18c3c7..4cc76ba5bc6 100644 --- a/docs/c-runtime-library/reference/realloc-dbg.md +++ b/docs/c-runtime-library/reference/realloc-dbg.md @@ -35,27 +35,27 @@ Pointer to the previously allocated memory block. Requested size for the reallocated block (bytes). *`blockType`*\ -Requested type for the reallocated block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +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**. +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**. +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`](../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 -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`](../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) 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** 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 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** 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). +**`_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). @@ -63,7 +63,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_realloc_dbg**|\| +|**`_realloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/realloc.md b/docs/c-runtime-library/reference/realloc.md index 150ad16441f..54d292b8e0d 100644 --- a/docs/c-runtime-library/reference/realloc.md +++ b/docs/c-runtime-library/reference/realloc.md @@ -35,9 +35,9 @@ New size in bytes. **`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 is not 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,11 +46,11 @@ 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`* is not `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. -**`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`** 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 diff --git a/docs/c-runtime-library/reference/recalloc-dbg.md b/docs/c-runtime-library/reference/recalloc-dbg.md index c3fe586dc53..82981fe8e94 100644 --- a/docs/c-runtime-library/reference/recalloc-dbg.md +++ b/docs/c-runtime-library/reference/recalloc-dbg.md @@ -39,29 +39,29 @@ Requested number of memory blocks. Requested size of each memory block (bytes). *`blockType`*\ -Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +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). *`filename`*\ -Pointer to name of the source file that requested allocation operation or **NULL**. +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**. +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`](../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 -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`](../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) 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** 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 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** 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). +**`_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). @@ -69,7 +69,7 @@ For information about how memory blocks are allocated, initialized, and managed |Routine|Required header| |-------------|---------------------| -|**_recalloc_dbg**|\| +|**`_recalloc_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/recalloc.md b/docs/c-runtime-library/reference/recalloc.md index 183f32f443b..657153e3d25 100644 --- a/docs/c-runtime-library/reference/recalloc.md +++ b/docs/c-runtime-library/reference/recalloc.md @@ -12,7 +12,7 @@ ms.assetid: 1db8305a-3f03-418c-8844-bf9149f63046 --- # `_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 @@ -37,23 +37,23 @@ Length in bytes of each element. ## 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 is not 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. ## 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`* is not `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`** is not 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`](../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` 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 ```C _set_new_mode(1); @@ -61,9 +61,9 @@ _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](/visualstudio/debugger/crt-debug-heap-details). -**_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 is not 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 behavior, 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 |Routine|Required header| |-------------|---------------------| -|**_recalloc**|\ and \| +|**`_recalloc`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md b/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md index 65f9ada32dc..7b905165410 100644 --- a/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md +++ b/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md @@ -36,13 +36,13 @@ The denominator. ## 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](../tgmath.md) for details. @@ -52,8 +52,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header (C)|Required header (C++)| |--------------|---------------------|-| -|**remainder**, **remainderf**, **remainderl**|\|\ or \| -|**remainder** macro | \ || +|**`remainder`**, **`remainderf`**, **`remainderl`**|\|\ or \| +|**`remainder`** macro | \ || For compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/remove-wremove.md b/docs/c-runtime-library/reference/remove-wremove.md index 62a108f0f36..ec451031773 100644 --- a/docs/c-runtime-library/reference/remove-wremove.md +++ b/docs/c-runtime-library/reference/remove-wremove.md @@ -31,7 +31,7 @@ Path of file to be removed. ## 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. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -43,7 +43,7 @@ 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| +|`TCHAR.H` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_tremove`**|**`remove`**|**`remove`**|**`_wremove`**| diff --git a/docs/c-runtime-library/reference/remquo-remquof-remquol.md b/docs/c-runtime-library/reference/remquo-remquof-remquol.md index 411891dfdeb..40cb59c9458 100644 --- a/docs/c-runtime-library/reference/remquo-remquof-remquol.md +++ b/docs/c-runtime-library/reference/remquo-remquof-remquol.md @@ -39,13 +39,13 @@ A pointer to an integer to store a value that has the sign and approximate magni ## 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`* = `n` \* *`y`* + `f`*, where `n` is an integer, `f` has the same sign as *`x`*, and the absolute value of `f` is less than the absolute value of *`y`*. +The **`remquo`** function calculates the floating-point remainder `f` of *`x`* / *`y`* such that *`x`* = `n` \* *`y`* + `f`*, where `n` is an integer, `f` has the same sign as *`x`*, and the absolute value of `f` is less than the absolute value of *`y`*. -C++ allows overloading, so you can call overloads of **remquo** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **remquo** always takes two **`double`** arguments and returns a **`double`**. +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](../tgmath.md) for details. @@ -55,8 +55,8 @@ By default, this function's global state is scoped to the application. To change |Function|Required header (C)|Required header (C++)| |--------------|---------------------|-| -|**remquo**, **remquof**, **remquol**|\|\ or \| -|**remquo** macro | \ || +|**`remquo`**, **`remquof`**, **`remquol`**|\|\ or \| +|**`remquo`** macro | \ || For compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rename-wrename.md b/docs/c-runtime-library/reference/rename-wrename.md index 459a2fe0465..1e8a2ec8697 100644 --- a/docs/c-runtime-library/reference/rename-wrename.md +++ b/docs/c-runtime-library/reference/rename-wrename.md @@ -37,13 +37,13 @@ Pointer to new name. ## 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 is 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. | +| `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. | For other possible return values, see [`_doserrno`, `_errno`, `syserrlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/resetstkoflw.md b/docs/c-runtime-library/reference/resetstkoflw.md index 4c0f5b88212..af92e52e963 100644 --- a/docs/c-runtime-library/reference/resetstkoflw.md +++ b/docs/c-runtime-library/reference/resetstkoflw.md @@ -31,7 +31,7 @@ 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 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). 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: @@ -73,7 +73,7 @@ It isn't safe to call **`_resetstkoflw`** in a C++ catch block that is reached f 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. -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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/rewind.md b/docs/c-runtime-library/reference/rewind.md index 62c4ab30a74..008ac3928ab 100644 --- a/docs/c-runtime-library/reference/rewind.md +++ b/docs/c-runtime-library/reference/rewind.md @@ -25,19 +25,19 @@ void rewind( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +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 );` -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 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. -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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -47,7 +47,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**rewind**|\| +|**`rewind`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rint-rintf-rintl.md b/docs/c-runtime-library/reference/rint-rintf-rintl.md index 7e0de487369..9d15db8f9b8 100644 --- a/docs/c-runtime-library/reference/rint-rintf-rintl.md +++ b/docs/c-runtime-library/reference/rint-rintf-rintl.md @@ -33,16 +33,16 @@ The floating-point value to round. ## 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| +|Input|SEH Exception|`_matherr` Exception| |-----------|-------------------|--------------------------| |± ∞, 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](../tgmath.md) for details. @@ -52,8 +52,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**rint**, **rintf**, **rintl**|\|\| -|**rint** macro | \ || +|**`rint`**, **`rintf`**, **`rintl`**|\|\| +|**`rint`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rmdir-wrmdir.md b/docs/c-runtime-library/reference/rmdir-wrmdir.md index 50fc495ad11..8bf70bc021b 100644 --- a/docs/c-runtime-library/reference/rmdir-wrmdir.md +++ b/docs/c-runtime-library/reference/rmdir-wrmdir.md @@ -32,36 +32,36 @@ Path of the directory to be removed. ## 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. | +| `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. | 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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_trmdir**|**_rmdir**|**_rmdir**|**_wrmdir**| +|`_trmdir`|**`_rmdir`**|**`_rmdir`**|**`_wrmdir`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_rmdir**|\| -|**_wrmdir**|\ or \| +|**`_rmdir`**|\| +|**`_wrmdir`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rmtmp.md b/docs/c-runtime-library/reference/rmtmp.md index 0706f342a19..bd6ddd4980d 100644 --- a/docs/c-runtime-library/reference/rmtmp.md +++ b/docs/c-runtime-library/reference/rmtmp.md @@ -23,11 +23,11 @@ int _rmtmp( void ); ## 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 behavior, see [Global state in the CRT](../global-state.md). @@ -35,7 +35,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_rmtmp**|\| +|**`_rmtmp`**|\| For more compatibility information, see [Compatibility](../compatibility.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 78e57a9bb0f..6dffc508ebc 100644 --- a/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md +++ b/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md @@ -12,7 +12,7 @@ ms.assetid: cfce439b-366f-4584-8ab1-d527b13fcfc6 --- # `_rotl`, `_rotl64`, `_rotr`, `_rotr64` -Rotates bits to the left (**_rotl**) or right (**_rotr**). +Rotates bits to the left (**`_rotl`**) or right (**`_rotr`**). ## Syntax @@ -50,14 +50,14 @@ 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**|\| +|**`_rotl`**, **`_rotl64`**|\| +|**`_rotr`**, **`_rotr64`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/round-roundf-roundl.md b/docs/c-runtime-library/reference/round-roundf-roundl.md index aca4ba443f8..869524f6df7 100644 --- a/docs/c-runtime-library/reference/round-roundf-roundl.md +++ b/docs/c-runtime-library/reference/round-roundf-roundl.md @@ -46,7 +46,7 @@ The **`round`** functions return a floating-point value that represents the near |Input|SEH Exception|Matherr Exception| |-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| +|± QNAN, IND|none|`_DOMAIN`| ## Remarks 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 ae58003564f..0cb47d9804a 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 @@ -43,7 +43,7 @@ _RPTFWn( ### Parameters *`reportType`*\ -Report type: **_CRT_WARN**, **_CRT_ERROR**, or **_CRT_ASSERT**. +Report type: `_CRT_WARN`, `_CRT_ERROR`, or `_CRT_ASSERT`. *`format`*\ Format-control string used to create the user message. @@ -53,36 +53,36 @@ 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 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. -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`](../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 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`](../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 **_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 neither `_CrtSetReportMode` nor `_CrtSetReportFile` has 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**.| +|`_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`.| -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, 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). -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|\| +|`_RPT` macros|\| +|`_RPTF` macros|\| +|`_RPTW` macros|\| +|`_RPTFW` macros|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rtc-geterrdesc.md b/docs/c-runtime-library/reference/rtc-geterrdesc.md index ea21723f14e..065ce001c60 100644 --- a/docs/c-runtime-library/reference/rtc-geterrdesc.md +++ b/docs/c-runtime-library/reference/rtc-geterrdesc.md @@ -25,17 +25,17 @@ const char * _RTC_GetErrDesc( ### Parameters *`errnum`*\ -A number between zero and one less than the value returned by **_RTC_NumErrors**. +A number between zero and one less than the value returned by `_RTC_NumErrors`. ## 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**|\| +|**`_RTC_GetErrDesc`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rtc-numerrors.md b/docs/c-runtime-library/reference/rtc-numerrors.md index 850d5e4ff44..5d1e1ff52c6 100644 --- a/docs/c-runtime-library/reference/rtc-numerrors.md +++ b/docs/c-runtime-library/reference/rtc-numerrors.md @@ -29,7 +29,7 @@ An integer whose value represents the total number of errors that can be detecte |Routine|Required header| |-------------|---------------------| -|**_RTC_NumErrors**|\| +|**`_RTC_NumErrors`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rtc-seterrorfunc.md b/docs/c-runtime-library/reference/rtc-seterrorfunc.md index 9ab60dbbc6a..07d7209e2e4 100644 --- a/docs/c-runtime-library/reference/rtc-seterrorfunc.md +++ b/docs/c-runtime-library/reference/rtc-seterrorfunc.md @@ -12,7 +12,7 @@ ms.assetid: b2292722-0d83-4092-83df-3d5b19880666 --- # `_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 @@ -29,17 +29,17 @@ The address of the function that will handle run-time error checks. ## Return value -The previously defined error function. If there is no previously defined function, returns **NULL**. +The previously defined error function. If there is no previously defined function, returns `NULL`. ## Remarks -Do not use this function; instead, use **_RTC_SetErrorFuncW**. It is retained only for backward compatibility. +Do not use this function; instead, use `_RTC_SetErrorFuncW`. It is retained only for backward compatibility. ## Requirements |Routine|Required header| |-------------|---------------------| -|**_RTC_SetErrorFunc**|\| +|**`_RTC_SetErrorFunc`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rtc-seterrorfuncw.md b/docs/c-runtime-library/reference/rtc-seterrorfuncw.md index 4f6758b1767..21680fdb1e7 100644 --- a/docs/c-runtime-library/reference/rtc-seterrorfuncw.md +++ b/docs/c-runtime-library/reference/rtc-seterrorfuncw.md @@ -29,21 +29,21 @@ The address of the function that will handle run-time error checks. ## 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 is 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. 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)( @@ -70,15 +70,15 @@ The line in *`filename`* where the failure occurred, or 0 if no debug informatio 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. +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 runtime 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**|\| +|**`_RTC_SetErrorFuncW`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/rtc-seterrortype.md b/docs/c-runtime-library/reference/rtc-seterrortype.md index d5498352772..14d1a3ac2bb 100644 --- a/docs/c-runtime-library/reference/rtc-seterrortype.md +++ b/docs/c-runtime-library/reference/rtc-seterrortype.md @@ -29,9 +29,9 @@ int _RTC_SetErrorType( 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`* values as there are *`errnum`* values. +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`* 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 @@ -39,7 +39,7 @@ 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 runtime checks without the C runtime library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library) @@ -47,7 +47,7 @@ Before you can call this function, you must first call one of the run-time error |Routine|Required header| |-------------|---------------------| -|**_RTC_SetErrorType**|\| +|**`_RTC_SetErrorType`**|\| For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/scalb.md b/docs/c-runtime-library/reference/scalb.md index 060a4cde1a7..b5ab0242ed5 100644 --- a/docs/c-runtime-library/reference/scalb.md +++ b/docs/c-runtime-library/reference/scalb.md @@ -36,7 +36,7 @@ Long integer exponent. ## 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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.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 4714510e039..f4050a24b89 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 @@ -12,7 +12,7 @@ ms.assetid: df2f1543-8e39-4af4-a5cf-29307e64807d --- # `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 @@ -76,15 +76,15 @@ Integer exponent. ## 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`](../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 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`**. 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. @@ -94,7 +94,7 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**scalbn**, **scalbnf**, **scalbnl**, **scalbln**, **scalblnf**, **scalblnl**|\|\| +|**`scalbn`**, **`scalbnf`**, **`scalbnl`**, **`scalbln`**, **`scalblnf`**, **`scalblnl`**|\|\| |**scalbn() or scalbln** macro | \ || For more compatibility information, see [Compatibility](../compatibility.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 b9ed187e1dd..aff4976336b 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 @@ -50,7 +50,7 @@ The locale to use. ## 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](../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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -60,7 +60,7 @@ The **`scanf_s`** function reads data from the standard input stream, **`stdin`* **`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: 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 f77649624c7..d1416bd33b0 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 @@ -55,7 +55,7 @@ The locale to use. Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. -If *`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`**. +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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.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 ab041d18d43..2ce616da7cd 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 @@ -49,11 +49,11 @@ The locale to use. ## 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 does not 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](../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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -61,7 +61,7 @@ For information about these and other error codes, see [`errno`, `_doserrno`, `_ 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. @@ -70,17 +70,17 @@ The versions of these functions with the **_l** suffix are identical except that ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_sctprintf_p**|**_scprintf_p**|**_scprintf_p**|**_scwprintf_p**| -|**_sctprintf_p_l**|**_scprintf_p_l**|**_scprintf_p_l**|**_scwprintf_p_l**| +|`_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 \| +|**`_scprintf_p`**, **`_scprintf_p_l`**|\| +|**`_scwprintf_p`**, **`_scwprintf_p_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 af3477b2309..ddb428d571a 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 @@ -51,9 +51,9 @@ For more information, see [Format specification syntax](../format-specification- ## 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 does not 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -61,7 +61,7 @@ For information about these and other error codes, see [`errno`, `_doserrno`, `_ 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. @@ -70,17 +70,17 @@ The versions of these functions with the **_l** suffix are identical except that ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_sctprintf**|**_scprintf**|**_scprintf**|**_scwprintf**| -|**_sctprintf_l**|**_scprintf_l**|**_scprintf_l**|**_scwprintf_l**| +|`_sctprintf`|**`_scprintf`**|**`_scprintf`**|**`_scwprintf`**| +|`_sctprintf_l`|**`_scprintf_l`**|**`_scprintf_l`**|**`_scwprintf_l`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_scprintf**, **_scprintf_l**|\| -|**_scwprintf**, **_scwprintf_l**|\ or \| +|**`_scprintf`**, **`_scprintf_l`**|\| +|**`_scwprintf`**, **`_scwprintf_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 710d9a4320f..77b57d3a4c3 100644 --- a/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md +++ b/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md @@ -64,27 +64,27 @@ Size of the *`pathname`* buffer. 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 |*`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| +|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](../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`* 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 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 *`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](../secure-template-overloads.md). @@ -92,16 +92,16 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsearchenv_s**|**_searchenv_s**|**_searchenv_s**|**_wsearchenv_s**| +|`_tsearchenv_s`|**`_searchenv_s`**|**`_searchenv_s`**|**`_wsearchenv_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_searchenv_s**|\| -|**_wsearchenv_s**|\ or \| +|**`_searchenv_s`**|\| +|**`_wsearchenv_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/searchenv-wsearchenv.md b/docs/c-runtime-library/reference/searchenv-wsearchenv.md index 9a0d2385a55..8907a89f338 100644 --- a/docs/c-runtime-library/reference/searchenv-wsearchenv.md +++ b/docs/c-runtime-library/reference/searchenv-wsearchenv.md @@ -57,19 +57,19 @@ 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 *`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](../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](../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](../secure-template-overloads.md). @@ -77,16 +77,16 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsearchenv**|**_searchenv**|**_searchenv**|**_wsearchenv**| +|`_tsearchenv`|**`_searchenv`**|**`_searchenv`**|**`_wsearchenv`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_searchenv**|\| -|**_wsearchenv**|\ or \| +|**`_searchenv`**|\| +|**`_wsearchenv`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-controlfp.md b/docs/c-runtime-library/reference/set-controlfp.md index 9b0eb27233a..2596bb2cab3 100644 --- a/docs/c-runtime-library/reference/set-controlfp.md +++ b/docs/c-runtime-library/reference/set-controlfp.md @@ -37,7 +37,7 @@ 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. @@ -45,7 +45,7 @@ This function is deprecated when compiling with [/clr (Common Language Runtime C |Routine|Required header|Compatibility| |-------------|---------------------|-------------------| -|**_set_controlfp**|\|x86 processor only| +|**`_set_controlfp`**|\|x86 processor only| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-doserrno.md b/docs/c-runtime-library/reference/set-doserrno.md index d47f1a72a15..5f4f70809c8 100644 --- a/docs/c-runtime-library/reference/set-doserrno.md +++ b/docs/c-runtime-library/reference/set-doserrno.md @@ -23,7 +23,7 @@ errno_t _set_doserrno( int error_value ); ### Parameters *`error_value`*\ -The new value of **_doserrno**. +The new value of `_doserrno`. ## Return value @@ -39,7 +39,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_set_doserrno**|\|\| +|**`_set_doserrno`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-errno.md b/docs/c-runtime-library/reference/set-errno.md index 8eeb5347a96..9c68400b118 100644 --- a/docs/c-runtime-library/reference/set-errno.md +++ b/docs/c-runtime-library/reference/set-errno.md @@ -12,7 +12,7 @@ ms.assetid: d338914a-1894-4cf3-ae45-f2c4eb26590b --- # `_set_errno` -Set the value of the **errno** global variable. +Set the value of the `errno` global variable. ## Syntax @@ -23,7 +23,7 @@ errno_t _set_errno( int error_value ); ### Parameters *`error_value`*\ -The new value of **errno**. +The new value of `errno`. ## Return value @@ -57,7 +57,7 @@ Oops: Illegal byte sequence |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_set_errno**|\|\| +|**`_set_errno`**|\|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-error-mode.md b/docs/c-runtime-library/reference/set-error-mode.md index 62a2b73a659..6bbc33be658 100644 --- a/docs/c-runtime-library/reference/set-error-mode.md +++ b/docs/c-runtime-library/reference/set-error-mode.md @@ -12,7 +12,7 @@ ms.assetid: f0807be5-73d1-4a32-a701-3c9bdd139c5c --- # `_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). @@ -36,26 +36,26 @@ 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. |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.| +|`_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](../parameter-validation.md). If execution is allowed to continue, **_set_error_mode** sets **errno** to **EINVAL** and returns -1. +If a value other than those listed is passed in, 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 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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**_set_error_mode**|\| +|**`_set_error_mode`**|\| ## Example diff --git a/docs/c-runtime-library/reference/set-fmode.md b/docs/c-runtime-library/reference/set-fmode.md index ee0abd5ac78..6c0128d8f19 100644 --- a/docs/c-runtime-library/reference/set-fmode.md +++ b/docs/c-runtime-library/reference/set-fmode.md @@ -25,17 +25,17 @@ errno_t _set_fmode( ### Parameters *`mode`*\ -The file translation mode desired: **_O_TEXT** or **_O_BINARY**. +The file translation mode desired: `_O_TEXT` or `_O_BINARY`. ## 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](../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`* is not `_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`](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_set_fmode**|\|\, \| +|**`_set_fmode`**|\|\, \| For more compatibility information, see [Compatibility](../compatibility.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 5d41253bbc7..d963c462682 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 @@ -36,7 +36,7 @@ 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. This allows 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. @@ -52,7 +52,7 @@ 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 behavior, see [Global state in the CRT](../global-state.md). @@ -60,9 +60,9 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_set_invalid_parameter_handler**, **_set_thread_local_invalid_parameter_handler**|C: \

C++: \ or \| +|**`_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](../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 diff --git a/docs/c-runtime-library/reference/set-new-handler.md b/docs/c-runtime-library/reference/set-new-handler.md index b1e611257ef..a50f596c788 100644 --- a/docs/c-runtime-library/reference/set-new-handler.md +++ b/docs/c-runtime-library/reference/set-new-handler.md @@ -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. diff --git a/docs/c-runtime-library/reference/set-new-mode.md b/docs/c-runtime-library/reference/set-new-mode.md index 50e609b282b..7c5fadccfa9 100644 --- a/docs/c-runtime-library/reference/set-new-mode.md +++ b/docs/c-runtime-library/reference/set-new-mode.md @@ -12,7 +12,7 @@ ms.assetid: 4d14039a-e54e-4689-8c70-74a4b9834768 --- # `_set_new_mode` -Sets a new handler mode for **malloc**. +Sets a new handler mode for `malloc`. ## Syntax @@ -23,15 +23,15 @@ int _set_new_mode( int newhandlermode ); ### Parameters *`newhandlermode`*\ -New handler mode for **malloc**; valid value is 0 or 1. +New handler mode for `malloc`; valid value is 0 or 1. ## 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 did not. If the *`newhandlermode`* argument does not 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` 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: ```cpp _set_new_mode(1); @@ -39,7 +39,7 @@ _set_new_mode(1); 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -47,7 +47,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_set_new_mode**|\| +|**`_set_new_mode`**|\| For more compatibility information, see [Compatibility](../compatibility.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 702ce6300c8..7f5e5092155 100644 --- a/docs/c-runtime-library/reference/set-printf-count-output.md +++ b/docs/c-runtime-library/reference/set-printf-count-output.md @@ -33,13 +33,13 @@ The state of **%n** support before calling this function: non-zero if **%n** sup ## 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](../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). +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**|\| +|**`_set_printf_count_output`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-se-translator.md b/docs/c-runtime-library/reference/set-se-translator.md index 15e11f21ae4..5d31dd7bb35 100644 --- a/docs/c-runtime-library/reference/set-se-translator.md +++ b/docs/c-runtime-library/reference/set-se-translator.md @@ -42,7 +42,7 @@ Your translator function should do no more than throw a C++ typed exception. If 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,7 +50,7 @@ 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 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. ## Requirements diff --git a/docs/c-runtime-library/reference/set-sse2-enable.md b/docs/c-runtime-library/reference/set-sse2-enable.md index 94c440faf55..e49f5c3a6fc 100644 --- a/docs/c-runtime-library/reference/set-sse2-enable.md +++ b/docs/c-runtime-library/reference/set-sse2-enable.md @@ -33,7 +33,7 @@ Nonzero if SSE2 implementation is enabled; zero if SSE2 implementation is disabl ## 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) @@ -54,7 +54,7 @@ The following functions have SSE2 implementations that can be enabled by using * 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. > [!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. @@ -62,7 +62,7 @@ The SSE2 implementation is only used if all exceptions are masked. Use [`_contro |Routine|Required header| |-------------|---------------------| -|**_set_SSE2_enable**|\| +|**`_set_SSE2_enable`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-terminate-crt.md b/docs/c-runtime-library/reference/set-terminate-crt.md index 4117d5ec8be..d8c9b5982fe 100644 --- a/docs/c-runtime-library/reference/set-terminate-crt.md +++ b/docs/c-runtime-library/reference/set-terminate-crt.md @@ -12,7 +12,7 @@ ms.assetid: 3ff1456a-7898-44bc-9266-a328a80b6006 --- # `set_terminate` (CRT) -Installs your own termination routine to be called by **terminate**. +Installs your own termination routine to be called by `terminate`. ## Syntax @@ -27,24 +27,24 @@ Pointer to a terminate function that you write. ## 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 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. 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 should not 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 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. By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -52,7 +52,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**set_terminate**|\| +|**`set_terminate`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/set-unexpected-crt.md b/docs/c-runtime-library/reference/set-unexpected-crt.md index f9cfa8a3cfd..244a72963b3 100644 --- a/docs/c-runtime-library/reference/set-unexpected-crt.md +++ b/docs/c-runtime-library/reference/set-unexpected-crt.md @@ -27,7 +27,7 @@ Pointer to a function that you write to replace the **`unexpected`** function. ## 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 diff --git a/docs/c-runtime-library/reference/setbuf.md b/docs/c-runtime-library/reference/setbuf.md index 674ec090ec3..15568c4f281 100644 --- a/docs/c-runtime-library/reference/setbuf.md +++ b/docs/c-runtime-library/reference/setbuf.md @@ -26,16 +26,16 @@ void setbuf( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,7 +43,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**setbuf**|\| +|**`setbuf`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/setmaxstdio.md b/docs/c-runtime-library/reference/setmaxstdio.md index 600d6687fc6..80e09d44436 100644 --- a/docs/c-runtime-library/reference/setmaxstdio.md +++ b/docs/c-runtime-library/reference/setmaxstdio.md @@ -30,7 +30,7 @@ New maximum for the number of simultaneously open files at the stream I/O level. 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/setmbcp.md b/docs/c-runtime-library/reference/setmbcp.md index 1fe7dc16f16..25b066dda7f 100644 --- a/docs/c-runtime-library/reference/setmbcp.md +++ b/docs/c-runtime-library/reference/setmbcp.md @@ -29,23 +29,23 @@ New code page setting for locale-independent multibyte routines. ## 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](../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 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](../interpretation-of-multibyte-character-sequences.md). 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). @@ -55,7 +55,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_setmbcp**|\| +|**`_setmbcp`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/setmode.md b/docs/c-runtime-library/reference/setmode.md index 799c6081b79..6d919444b78 100644 --- a/docs/c-runtime-library/reference/setmode.md +++ b/docs/c-runtime-library/reference/setmode.md @@ -35,15 +35,15 @@ New translation mode. 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](../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 [`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 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. diff --git a/docs/c-runtime-library/reference/setvbuf.md b/docs/c-runtime-library/reference/setvbuf.md index ef95aad507d..91757816cf2 100644 --- a/docs/c-runtime-library/reference/setvbuf.md +++ b/docs/c-runtime-library/reference/setvbuf.md @@ -28,7 +28,7 @@ int setvbuf( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`buffer`*\ User-allocated buffer. @@ -43,21 +43,21 @@ Buffer size in bytes. Allowable range: 2 <= *`size`* <= INT_MAX (2147483647). In 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](../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`* is not 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 [`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 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 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 *`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`*. | +| `_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`*. | By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -65,7 +65,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**setvbuf**|\| +|**`setvbuf`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/signal.md b/docs/c-runtime-library/reference/signal.md index cc4da08ca23..f909c70c4ca 100644 --- a/docs/c-runtime-library/reference/signal.md +++ b/docs/c-runtime-library/reference/signal.md @@ -28,11 +28,11 @@ void __cdecl *signal(int sig, int (*func)(int, int)); 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`**. +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`. ## 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`](../errno-doserrno-sys-errlist-and-sys-nerr.md) for more information about return codes. @@ -42,29 +42,29 @@ The **`signal`** function enables a process to choose one of several ways to han |*`sig`* value|Description| |-----------------|-----------------| -|**`SIGABRT`**|Abnormal termination| -|**`SIGFPE`**|Floating-point error| -|**`SIGILL`**|Illegal instruction| -|**`SIGINT`**|CTRL+C signal| -|**`SIGSEGV`**|Illegal storage access| -|**`SIGTERM`**|Termination request| +|`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](../parameter-validation.md) . If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns **`SIG_ERR`**. +If *`sig`* is not 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 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. -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 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. 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. 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. -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. @@ -74,17 +74,17 @@ Because signal-handler routines are usually called asynchronously when an interr - Do not 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`**. +- 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`**. - Do not 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 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: ```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 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). Signal settings are not 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. @@ -98,7 +98,7 @@ 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 additional information about abort behavior, see [`_set_abort_behavior`](set-abort-behavior.md). ```C // crt_signal.c diff --git a/docs/c-runtime-library/reference/signbit.md b/docs/c-runtime-library/reference/signbit.md index 51e31d1468c..85aecf1528b 100644 --- a/docs/c-runtime-library/reference/signbit.md +++ b/docs/c-runtime-library/reference/signbit.md @@ -36,17 +36,17 @@ 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 \| +|**`signbit`**|\|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md b/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md index 9dbe17257a3..4c01ff749e1 100644 --- a/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md +++ b/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md @@ -32,7 +32,7 @@ Angle in radians. ## 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| |-----------|-------------------|-----------------------| 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 b8f7b001ffd..ccdc778dd0e 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 @@ -86,9 +86,9 @@ The locale to use. **`_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. -If the storage required to store the data and a terminating null exceeds *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *`buffer`* to an empty string, set **`errno`** to **`ERANGE`**, and return -1. +If the storage required to store the data and a terminating null exceeds *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *`buffer`* to an empty string, set `errno` to `ERANGE`, and return -1. -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. +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. For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -104,7 +104,7 @@ If *`count`* is [`_TRUNCATE`](../truncate.md), then **`_snprintf_s`** writes as > > 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`**. +**`_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. 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 6b14201726c..6b745a97789 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 @@ -111,7 +111,7 @@ For all functions other than **`snprintf`**, if **`len`** = *`count`*, **`len`** 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. -If *`buffer`* is a null pointer and *`count`* is nonzero, or if *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +If *`buffer`* is a null pointer and *`count`* is nonzero, or if *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -126,7 +126,7 @@ The **`snprintf`** function and the **`_snprintf`** family of functions format a 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 that in **`_snprintf`**. **`_snwprintf`**, just like **`swprintf`**, writes output to a string instead of a destination of type `FILE`. The versions of these functions that have the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. diff --git a/docs/c-runtime-library/reference/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 3852d97f4c3..450679c6d18 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 @@ -60,36 +60,36 @@ Optional arguments to be assigned according to the format string. ## 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 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). -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**. +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 [`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 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). 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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \| +|**`_snscanf_s`**, **`_snscanf_s_l`**|\| +|**`_snwscanf_s`**, **`_snwscanf_s_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 076c7a7b187..a2fdd1d1e23 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 @@ -64,31 +64,31 @@ The locale to use. ## 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 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). -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**. +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 [`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 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). -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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_sntscanf**|**_snscanf**|**_snscanf**|**_snwscanf**| -|**_sntscanf_l**|**_snscanf_l**|**_snscanf_l**|**_snwscanf_l**| +|`_sntscanf`|**`_snscanf`**|**`_snscanf`**|**`_snwscanf`**| +|`_sntscanf_l`|**`_snscanf_l`**|**`_snscanf_l`**|**`_snwscanf_l`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_snscanf**, **_snscanf_l**|\| -|**_snwscanf**, **_snwscanf_l**|\ or \| +|**`_snscanf`**, **`_snscanf_l`**|\| +|**`_snwscanf`**, **`_snwscanf_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 92edae0d77b..0babce7948e 100644 --- a/docs/c-runtime-library/reference/sopen-s-wsopen-s.md +++ b/docs/c-runtime-library/reference/sopen-s-wsopen-s.md @@ -52,17 +52,17 @@ 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](../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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -84,48 +84,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](../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 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).) diff --git a/docs/c-runtime-library/reference/sopen-wsopen.md b/docs/c-runtime-library/reference/sopen-wsopen.md index 64e11ad714a..c9062dbbd1c 100644 --- a/docs/c-runtime-library/reference/sopen-wsopen.md +++ b/docs/c-runtime-library/reference/sopen-wsopen.md @@ -49,15 +49,15 @@ 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -77,48 +77,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](../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 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). diff --git a/docs/c-runtime-library/reference/spawnl-wspawnl.md b/docs/c-runtime-library/reference/spawnl-wspawnl.md index c890468532e..11328c09cc0 100644 --- a/docs/c-runtime-library/reference/spawnl-wspawnl.md +++ b/docs/c-runtime-library/reference/spawnl-wspawnl.md @@ -47,23 +47,23 @@ Execution mode for the calling process. 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. +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 -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 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. | 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 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. | 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](../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 @@ -73,8 +73,8 @@ Each of these functions creates and executes a new process, passing each command |Routine|Required header| |-------------|---------------------| -|**_spawnl**|\| -|**_wspawnl**|\ or \| +|**`_spawnl`**|\| +|**`_wspawnl`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnle-wspawnle.md b/docs/c-runtime-library/reference/spawnle-wspawnle.md index 32f84197316..90633ba5856 100644 --- a/docs/c-runtime-library/reference/spawnle-wspawnle.md +++ b/docs/c-runtime-library/reference/spawnle-wspawnle.md @@ -49,22 +49,22 @@ Execution mode for the calling process. 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. +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`*\ Array of pointers to environment settings. ## 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 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. | 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 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. | 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). @@ -72,14 +72,14 @@ For more information about these and other return codes, see [`errno`, `_doserrn 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](../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 \| +|**`_spawnle`**|\| +|**`_wspawnle`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnlp-wspawnlp.md b/docs/c-runtime-library/reference/spawnlp-wspawnlp.md index b4460f74a00..b3674aa822a 100644 --- a/docs/c-runtime-library/reference/spawnlp-wspawnlp.md +++ b/docs/c-runtime-library/reference/spawnlp-wspawnlp.md @@ -47,34 +47,34 @@ Execution mode for the calling process. 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. +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 -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 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. | 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 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. | 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](../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 \| +|**`_spawnlp`**|\| +|**`_wspawnlp`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md b/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md index 8810fa001d5..b5dbb25c3cc 100644 --- a/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md +++ b/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md @@ -49,37 +49,37 @@ Execution mode for the calling process. 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. +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`*\ Array of pointers to environment settings. ## 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 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. | 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 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. | 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](../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 \| +|**`_spawnlpe`**|\| +|**`_wspawnlpe`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnv-wspawnv.md b/docs/c-runtime-library/reference/spawnv-wspawnv.md index 133581c4967..489fdd15e79 100644 --- a/docs/c-runtime-library/reference/spawnv-wspawnv.md +++ b/docs/c-runtime-library/reference/spawnv-wspawnv.md @@ -41,19 +41,19 @@ Execution mode for the calling process. 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. +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 -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 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. | 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 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. | 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). @@ -61,7 +61,7 @@ For more information about these and other return codes, see [`errno`, `_doserrn 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -69,8 +69,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_spawnv**|\ or \| -|**_wspawnv**|\ or \| +|**`_spawnv`**|\ or \| +|**`_wspawnv`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnve-wspawnve.md b/docs/c-runtime-library/reference/spawnve-wspawnve.md index bff63b3c5ab..544ce896d3d 100644 --- a/docs/c-runtime-library/reference/spawnve-wspawnve.md +++ b/docs/c-runtime-library/reference/spawnve-wspawnve.md @@ -43,22 +43,22 @@ Execution mode for a calling process. 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. +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`*\ Array of pointers to environment settings. ## 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 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. | 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 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. | 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). @@ -66,7 +66,7 @@ For more information about these and other return codes, see [`errno`, `_doserrn 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -74,8 +74,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_spawnve**|\ or \| -|**_wspawnve**|\ or \| +|**`_spawnve`**|\ or \| +|**`_wspawnve`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnvp-wspawnvp.md b/docs/c-runtime-library/reference/spawnvp-wspawnvp.md index bd255f71f6b..049425f961e 100644 --- a/docs/c-runtime-library/reference/spawnvp-wspawnvp.md +++ b/docs/c-runtime-library/reference/spawnvp-wspawnvp.md @@ -41,27 +41,27 @@ Execution mode for calling the process. 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. +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 -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 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: | 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 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. | 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 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -69,8 +69,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_spawnvp**|\ or \| -|**_wspawnvp**|\ or \| +|**`_spawnvp`**|\ or \| +|**`_wspawnvp`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md b/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md index 4cb3939f32b..a4ab14074bd 100644 --- a/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md +++ b/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md @@ -43,30 +43,30 @@ Execution mode for calling process 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. +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`*\ Array of pointers to environment settings ## 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 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: +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 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. | +| `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 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -74,8 +74,8 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_spawnvpe**|\ or \| -|**_wspawnvpe**|\ or \| +|**`_spawnvpe`**|\ or \| +|**`_wspawnvpe`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 88440b01f87..4e0660f7482 100644 --- a/docs/c-runtime-library/reference/splitpath-s-wsplitpath-s.md +++ b/docs/c-runtime-library/reference/splitpath-s-wsplitpath-s.md @@ -63,28 +63,28 @@ errno_t _wsplitpath_s( 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 letter, followed by a colon (**`:`**). You can pass `NULL` for this parameter if you do not 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. +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. +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. *`dirNumberOfElements`*\ -The size of the *`dir`* buffer in single-byte or wide characters. If *`dir`* is **`NULL`**, this value must be 0. +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. +Base filename (without extension). You can pass `NULL` for this parameter if you do not 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. +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. +Filename extension, including leading period (**`.`**). You can pass `NULL` for this parameter if you do not 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. +The size of *`ext`* buffer in single-byte or wide characters. If *`ext`* is `NULL`, this value must be 0. ## Return value @@ -94,19 +94,19 @@ Zero if successful; an error code on failure. |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`**| +|*`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](../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 @@ -120,7 +120,7 @@ By default, this function's global state is scoped to the application. To change |---------------------|------------------------------------|--------------------|-----------------------| |**`_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. diff --git a/docs/c-runtime-library/reference/splitpath-wsplitpath.md b/docs/c-runtime-library/reference/splitpath-wsplitpath.md index 9c55bdfe73c..e0e3e6c2fbd 100644 --- a/docs/c-runtime-library/reference/splitpath-wsplitpath.md +++ b/docs/c-runtime-library/reference/splitpath-wsplitpath.md @@ -39,16 +39,16 @@ void _wsplitpath( 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 letter, followed by a colon (**:**). You can pass `NULL` for this parameter if you do not 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. +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. *`fname`*\ -Base filename (no extension). You can pass **`NULL`** for this parameter if you do not need the filename. +Base filename (no extension). You can pass `NULL` for this parameter if you do not need the filename. *`ext`*\ -Filename extension, including leading period (**.**). You can pass **`NULL`** for this parameter if you do not need the filename extension. +Filename extension, including leading period (**.**). You can pass `NULL` for this parameter if you do not need the filename extension. ## Remarks @@ -64,7 +64,7 @@ By default, this function's global state is scoped to the application. To change |---------------------|------------------------------------|--------------------|-----------------------| |**`_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. @@ -72,16 +72,16 @@ The following table lists the values of the manifest constants. |Name|Value| |----------|-----------| -|**`_MAX_DRIVE`**|3| -|**`_MAX_DIR`**|256| -|**`_MAX_FNAME`**|256| -|**`_MAX_EXT`**|256| +|`_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. -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 do not need. -If *`path`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`errno`** is set to **`EINVAL`** and the function returns **`EINVAL`**. +If *`path`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `EINVAL`. ## Requirements 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 71c19016ba3..18f2bea8f44 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 @@ -71,9 +71,9 @@ The number of characters written, or -1 if an error occurred. 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 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. -**`_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`**. +**`_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). 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 ab533aaa07e..38254202c73 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 @@ -77,40 +77,40 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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 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. 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](../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 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). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). ### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \| +|**`sprintf_s`**, **`_sprintf_s_l`**|C: \

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

C++: \, \, \ or \| For more compatibility information, see [Compatibility](../compatibility.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 45873ee1771..db00de8c6a0 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 @@ -82,7 +82,7 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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. @@ -95,9 +95,9 @@ The **`sprintf`** function formats and stores a series of characters and values > > 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. +**`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. 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). 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 fac3fde9d0a..606559169c1 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 @@ -57,9 +57,9 @@ The locale to use ## 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 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. -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`** +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`](../errno-doserrno-sys-errlist-and-sys-nerr.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 29b49103def..6fac26690fd 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 @@ -57,9 +57,9 @@ The locale to use ## 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 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. -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`**. +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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). diff --git a/docs/c-runtime-library/reference/stat-functions.md b/docs/c-runtime-library/reference/stat-functions.md index b85ca16501b..fe38253d2dc 100644 --- a/docs/c-runtime-library/reference/stat-functions.md +++ b/docs/c-runtime-library/reference/stat-functions.md @@ -77,11 +77,11 @@ Pointer to structure that stores results. ## 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 couldn't 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. 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'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. +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 @@ -89,20 +89,20 @@ The **`_stat`** function obtains information about the file or directory specifi **`_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-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. -**`_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`**. +**`_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. -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). +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 behavior, see [Global state in the CRT](../global-state.md). ### Time type and file length type variations of `_stat` -|Functions|_USE_32BIT_TIME_T defined?|Time type|File length type| +|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| @@ -132,7 +132,7 @@ The **`_stat`** structure, defined in **`SYS\STAT.H`**, includes the following f | **`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`**). | diff --git a/docs/c-runtime-library/reference/static-assert-macro.md b/docs/c-runtime-library/reference/static-assert-macro.md index e897c249340..8e710144c0c 100644 --- a/docs/c-runtime-library/reference/static-assert-macro.md +++ b/docs/c-runtime-library/reference/static-assert-macro.md @@ -11,7 +11,7 @@ ms.assetid: 89b0350c-2c2f-4be6-9786-8b1f0780a5da --- # `_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 @@ -24,11 +24,11 @@ _STATIC_ASSERT( ### Parameters *`booleanExpression`*\ -Expression (including pointers) that evaluates to nonzero (**TRUE**) or 0 (**FALSE**). +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 @@ -56,7 +56,7 @@ int main() |Macro|Required header| |-----------|---------------------| -|**_STATIC_ASSERT**|\| +|`_STATIC_ASSERT`|\| ## See also diff --git a/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md b/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md index 54769c0a520..f344994eb0f 100644 --- a/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md +++ b/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md @@ -32,15 +32,15 @@ This address is filled with the status word for the SSE2 floating-point unit. ## 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. 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. -**_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 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`**. -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. @@ -48,7 +48,7 @@ These functions are not useful for [/clr (Common Language Runtime Compilation)]( |Routine|Required header| |-------------|---------------------| -|**_status87**, **_statusfp**, **_statusfp2**|\| +|**`_status87`**, **`_statusfp`**, **`_statusfp2`**|\| For more compatibility information, see [Compatibility](../compatibility.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 ec02e6060ca..6563794401e 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 @@ -86,9 +86,9 @@ Zero if successful; an error code on failure. |*`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| +|`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 @@ -105,7 +105,7 @@ 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. -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](../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 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](../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](../locale.md). diff --git a/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md b/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md index 194449223da..80c2e767794 100644 --- a/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md +++ b/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md @@ -57,11 +57,11 @@ The return value for each of these functions indicates the ordinal relation of * |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](../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`** 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`** do not validate their parameters. These functions behave identically otherwise. By default, this function's global state is scoped to the application. To change this behavior, 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 |---------------------|------------------------------------|--------------------|-----------------------| |**`_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 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). 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. 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 e7a22a0847d..b68603b5edb 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 @@ -12,10 +12,10 @@ ms.assetid: 900a7540-c7ec-4c2f-b292-7a85f63e3fe8 --- # `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 @@ -67,33 +67,33 @@ Each of these functions returns a value indicating the relationship of *`string1 |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. -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**. +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](../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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcscoll**|**strcoll**|**_mbscoll**|**wcscoll**| +|`_tcscoll`|**`strcoll`**|**`_mbscoll`**|**`wcscoll`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**strcoll**|\| -|**wcscoll**|\, \| -|**_mbscoll**, **_mbscoll_l**|\| -|**_strcoll_l**|\| -|**_wcscoll_l**|\, \| +|**`strcoll`**|\| +|**`wcscoll`**|\, \| +|**`_mbscoll`**, **`_mbscoll_l`**|\| +|**`_strcoll_l`**|\| +|**`_wcscoll_l`**|\, \| For more compatibility information, see [Compatibility](../compatibility.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 98a263a927a..e7c9b348e8b 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 @@ -74,7 +74,7 @@ errno_t _mbscpy_s_l( 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. +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`*\ Null-terminated source string buffer. @@ -90,9 +90,9 @@ Zero if successful; otherwise, an error. |*`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| +|`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 @@ -100,7 +100,7 @@ The **`strcpy_s`** function copies the contents in the address of *`src`*, inclu **`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`](../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](../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. 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 84161e31e16..56289b604e2 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 @@ -15,7 +15,7 @@ ms.assetid: f73f51dd-b533-4e46-ba29-d05c553708a6 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 @@ -58,28 +58,28 @@ 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; those 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](../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`** do not 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](../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](../locale.md). By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcscspn**|**strcspn**|**_mbscspn**|**wcscspn**| -|n/a|n/a|**_mbscspn_l**|n/a| +|`_tcscspn`|**`strcspn`**|**`_mbscspn`**|**`wcscspn`**| +|n/a|n/a|**`_mbscspn_l`**|n/a| ## Requirements |Routine|Required header| |-------------|---------------------| -|**strcspn**|\| -|**wcscspn**|\ or \| -|**_mbscspn**, **_mbscspn_l**|\| +|**`strcspn`**|\| +|**`wcscspn`**|\ or \| +|**`_mbscspn`**, **`_mbscspn_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 8167a00ec0b..27ebc7f54be 100644 --- a/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md +++ b/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md @@ -51,10 +51,10 @@ Zero if successful. The return value is an error code if there's a failure. Erro |*`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| +|`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 @@ -64,11 +64,11 @@ Passing a value for *`size`* greater than the actual size of *`buffer`* results ## 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](../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](../secure-template-overloads.md). @@ -78,17 +78,17 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mapping: -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrdate_s**|**_strdate_s**|**_strdate_s**|**_wstrdate_s**| +|`_tstrdate_s`|**`_strdate_s`**|**`_strdate_s`**|**`_wstrdate_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strdate**|\| -|**_wstrdate**|\ or \| -|**_strdate_s**|\| +|**`_strdate`**|\| +|**`_wstrdate`**|\ or \| +|**`_strdate_s`**|\| ## Example diff --git a/docs/c-runtime-library/reference/strdate-wstrdate.md b/docs/c-runtime-library/reference/strdate-wstrdate.md index 1f0984842bc..8c8fb1a13da 100644 --- a/docs/c-runtime-library/reference/strdate-wstrdate.md +++ b/docs/c-runtime-library/reference/strdate-wstrdate.md @@ -46,11 +46,11 @@ Each of these functions returns a pointer to the resulting character string *`da 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. -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](../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](../secure-template-overloads.md). @@ -58,16 +58,16 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrdate**|**_strdate**|**_strdate**|**_wstrdate**| +|`_tstrdate`|**`_strdate`**|**`_strdate`**|**`_wstrdate`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strdate**|\| -|**_wstrdate**|\ or \| +|**`_strdate`**|\| +|**`_wstrdate`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 9eee92e2ba2..26db67cd8d9 100644 --- a/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md +++ b/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md @@ -15,7 +15,7 @@ ms.assetid: ae37c223-800f-48a9-ae8e-38c8d20af2dd Moves a string pointer back one character. > [!IMPORTANT] -> **mbsdec** and **mbsdec_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`mbsdec`** and **`mbsdec_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -42,25 +42,25 @@ 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. +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. +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 to use. ## 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](../locale.md). +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](../locale.md). -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**. +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). @@ -69,11 +69,11 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsdec**|**_strdec**|**_mbsdec**|**_wcsdec**| +|`_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 should not be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). @@ -81,16 +81,16 @@ For more information, see [Using generic-text mappings](../using-generic-text-ma |Routine|Required header|Optional header| |-------------|---------------------|---------------------| -|**_mbsdec**|\|\| -|**_mbsdec_l**|\|\| -|**_strdec**|\|| -|**_wcsdec**|\|| +|**`_mbsdec`**|\|\| +|**`_mbsdec_l`**|\|\| +|**`_strdec`**|\|| +|**`_wcsdec`**|\|| 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 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 d2dcca5c9b2..3aafa77a652 100644 --- a/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md +++ b/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md @@ -12,7 +12,7 @@ ms.assetid: 681db70c-d124-43ab-b83e-5eeea9035097 --- # `_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 @@ -37,35 +37,35 @@ wchar_t *_wcsdup_dbg( Null-terminated source string. *`blockType`*\ -Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. *`filename`*\ -Pointer to name of source file that requested allocation operation or **NULL**. +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**. +Line number in source file where allocation operation was requested or `NULL`. ## 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 cannot 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 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). ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsdup_dbg**|**_strdup_dbg**|**_mbsdup**|**_wcsdup_dbg**| +|`_tcsdup_dbg`|**`_strdup_dbg`**|`_mbsdup`|**`_wcsdup_dbg`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strdup_dbg**, **_wcsdup_dbg**|\| +|**`_strdup_dbg`**, **`_wcsdup_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md b/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md index 0336e7750e0..d007cb7e574 100644 --- a/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md +++ b/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md @@ -38,7 +38,7 @@ Null-terminated source string. ## 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 cannot be allocated. ## Remarks @@ -56,7 +56,7 @@ By default, this function's global state is scoped to the application. To change 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`**. -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 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 3260b8c0810..b35563b785c 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 @@ -12,7 +12,7 @@ ms.assetid: 9e5b15a0-efe1-4586-b7e3-e1d7c31a03d6 --- # `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](../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 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 @@ -87,14 +87,14 @@ Zero if successful, an error code on failure. |*`buffer`*|*`sizeInBytes`*/*`sizeInWords`*|*`strErrMsg`*|Contents of *`buffer`*| |--------------|------------------------|-----------------|--------------------------| -|**NULL**|any|any|n/a| +|`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. 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): ```C if (( _access( "datafile",2 )) == -1 ) @@ -104,17 +104,17 @@ 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. 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. 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. -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 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 returns 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](../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](../secure-template-overloads.md). @@ -124,16 +124,16 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcserror_s**|**strerror_s**|**strerror_s**|**_wcserror_s**| +|`_tcserror_s`|**`strerror_s`**|**`strerror_s`**|**`_wcserror_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**strerror_s**, **_strerror_s**|\| -|**_wcserror_s**, **__wcserror_s**|\ or \| +|**`strerror_s`**, **`_strerror_s`**|\| +|**`_wcserror_s`**, **`__wcserror_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 b100570f31a..f341c9b8a3d 100644 --- a/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md +++ b/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md @@ -12,7 +12,7 @@ ms.assetid: 27b72255-f627-43c0-8836-bcda8b003e14 --- # `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 @@ -44,38 +44,38 @@ 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. 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. -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. +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`](../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**. +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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcserror**|**strerror**|**strerror**|**_wcserror**| +|`_tcserror`|**`strerror`**|**`strerror`**|**`_wcserror`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**strerror**|\| -|**_strerror**|\| -|**_wcserror**, **__wcserror**|\| +|**`strerror`**|\| +|**`_strerror`**|\| +|**`_wcserror`**, **`__wcserror`**|\| For more compatibility information, see [Compatibility](../compatibility.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 3a31444bf16..0c2b8e17399 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 @@ -74,7 +74,7 @@ The number of characters in *`strDest`* is equal to the number of literal charac 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -84,7 +84,7 @@ By default, this function's global state is scoped to the application. To change |---------------------|------------------------------------|--------------------|-----------------------| |**`_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](../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 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](../locale.md). The **`strftime`** functions support these formatting codes: 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 6c824e82c3f..19e57172a3e 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 @@ -67,11 +67,11 @@ The return value indicates the relation of *`string1`* to *`string2`* as follows |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](../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](../locale.md). +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](../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](../locale.md). > [!NOTE] > **`_stricmp`** is equivalent to **`_strcmpi`**. They can be used interchangeably but **`_stricmp`** is the preferred standard. @@ -84,7 +84,7 @@ 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](../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; 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](../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. @@ -108,7 +108,7 @@ 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](../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 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 dac0332e70e..85e4d4ffd0e 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 @@ -15,7 +15,7 @@ ms.assetid: 8ec93016-5a49-49d2-930f-721566661d82 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 @@ -66,33 +66,33 @@ Each of these functions returns a value indicating the relationship of *`string1 |< 0|*`string1`* less than *`string2`*| |0|*`string1`* identical to *`string2`*| |> 0|*`string1`* greater than *`string2`*| -|**_NLSCMPERROR**|An error occurred.| +|`_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. -**_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). +`_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](../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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsicoll**|**_stricoll**|**_mbsicoll**|**_wcsicoll**| +|`_tcsicoll`|**`_stricoll`**|**`_mbsicoll`**|**`_wcsicoll`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_stricoll**, **_stricoll_l**|\| -|**_wcsicoll**, **_wcsicoll_l**|\, \| -|**_mbsicoll**, **_mbsicoll_l**|\| +|**`_stricoll`**, **`_stricoll_l`**|\| +|**`_wcsicoll`**, **`_wcsicoll_l`**|\, \| +|**`_mbsicoll`**, **`_mbsicoll_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 91d8d6e641e..b05e0c73d00 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 @@ -15,7 +15,7 @@ ms.assetid: 54685943-8e2c-45e9-a559-2d94930dc6b4 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 @@ -51,11 +51,11 @@ Each of these routines returns a pointer to the character that immediately follo ## 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](../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 **`_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](../using-generic-text-mappings.md) and [Generic-text mappings](../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 should not 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](../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). @@ -66,10 +66,10 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_mbsinc**|\| -|**_mbsinc_l**|\| -|**_strinc**|\| -|**_wcsinc**|\| +|**`_mbsinc`**|\| +|**`_mbsinc_l`**|\| +|**`_strinc`**|\| +|**`_wcsinc`**|\| For more compatibility information, see [Compatibility](../compatibility.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 c89137f6d72..f3ae8c10975 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 @@ -70,9 +70,9 @@ By default, this function's global state is scoped to the application. To change |**`_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 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`. -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](../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](../locale.md). ## Requirements 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 5c19e40d180..2d0e9c3e147 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 @@ -15,7 +15,7 @@ ms.assetid: 4883d31b-bdac-4049-83a1-91dfdeceee79 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 @@ -91,13 +91,13 @@ The locale to use. 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](../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`* is not 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](../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](../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](../secure-template-overloads.md). @@ -107,18 +107,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| +|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**| +|`_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 \| +|**`_strlwr_s`**, **`_strlwr_s_l`**|\| +|**`_mbslwr_s`**, **`_mbslwr_s_l`**|\| +|**`_wcslwr_s`**, **`_wcslwr_s_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 3d8dabf1a73..f2541ebd911 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 @@ -15,7 +15,7 @@ ms.assetid: d279181d-2e7d-401f-ab44-6e7c2786a046 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 @@ -84,11 +84,11 @@ Each of these functions returns a pointer to the converted string. Because the m ## 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](../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 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](../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; those 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](../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](../secure-template-overloads.md). @@ -96,18 +96,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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcslwr**|**_strlwr**|**_mbslwr**|**_wcslwr**| -|**_tcslwr_l**|**_strlwr_l**|**_mbslwr_l**|**_wcslwr_l**| +|`_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**|\| +|**`_strlwr`**, **`_strlwr_l`**|\| +|**`_wcslwr`**, **`_wcslwr_l`**|\ or \| +|**`_mbslwr`**, **`_mbslwr_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 498fe6513c2..e7e5cdc6074 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 @@ -15,7 +15,7 @@ ms.assetid: de77eca2-4d9c-4e66-abf2-a95fefc21e5a 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 @@ -125,9 +125,9 @@ Returns 0 if successful, an error code on failure. |*`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| +|`NULL` or unterminated|any|any|`EINVAL`|not modified| +|any|any|`NULL`|`EINVAL`|not modified| +|any|0, or too small|any|`ERANGE`|not modified| ## Remarks @@ -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; this would leave no space for the null terminator, hence **`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,11 +159,11 @@ 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](../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; those 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](../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](../secure-template-overloads.md). @@ -173,20 +173,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| +|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**| +|`_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 are only provided for **`_tcsncat_s_l`**. ## Requirements |Routine|Required header| |-------------|---------------------| -|**strncat_s**|\| -|**wcsncat_s**|\ or \| -|**_mbsncat_s**, **_mbsncat_s_l**|\| +|**`strncat_s`**|\| +|**`wcsncat_s`**|\ or \| +|**`_mbsncat_s`**, **`_mbsncat_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 ac6c60fef04..b4baaba91d1 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 @@ -94,7 +94,7 @@ The **`strncat`** function appends, at most, the first *`count`* characters of * **`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. -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](../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) 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](../locale.md). In C++, these functions have template overloads. For more information, see [Secure template overloads](../secure-template-overloads.md). @@ -168,7 +168,7 @@ 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. +Note that `BadAppend` caused a buffer overrun. ## See also 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 de4e74819a0..497ed1ded99 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 @@ -74,11 +74,11 @@ On a parameter validation error, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_ 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; those 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](../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`* is not 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`** do not 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](../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 behavior, see [Global state in the CRT](../global-state.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 dda63446129..37f85fea426 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 @@ -15,7 +15,7 @@ ms.assetid: 2a022e9e-a307-4acb-a66b-e56e5357f848 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 @@ -61,42 +61,42 @@ Locale to use. ## 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 is not 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](../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](../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](../locale.md). By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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**|\| +|**`_mbsnbcnt`**|\| +|**`_mbsnbcnt_l`**|\| +|**`_mbsnccnt`**|\| +|**`_mbsnccnt_l`**|\| +|**`_strncnt`**|\| +|**`_wcsncnt`**|\| For more compatibility information, see [Compatibility](../compatibility.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 3e9588986a6..98902a2bef2 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 @@ -15,7 +15,7 @@ ms.assetid: e659a5a4-8afe-4033-8e72-17ffd4bdd8e9 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 @@ -76,30 +76,30 @@ Each of these functions returns a value that indicates the relationship of the s |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 you call **`_wcsncoll`**. ## 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](../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 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](../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](../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 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| +|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**| +|`_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**|\| +|**`_strncoll`**, **`_strncoll_l`**|\| +|**`_wcsncoll`**, **`_wcsncoll_l`**|\ or \| +|**`_mbsncoll`**, **`_mbsncoll_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 3e9172296ed..5341a742f93 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 @@ -119,22 +119,22 @@ The locale to use. ## 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 |*`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| +|`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](../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 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. For example, @@ -145,7 +145,7 @@ 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. -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); @@ -156,11 +156,11 @@ Note that unlike **`strncpy`**, if *`count`* is greater than the length of *`str 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](../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](../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](../secure-template-overloads.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 6cb4cd96529..899f32e4801 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 @@ -119,7 +119,7 @@ The **`strncpy`** function copies the initial *`count`* characters of *`strSourc > [!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). -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`**. +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. 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 e0a60fe5a32..09969f95bae 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 @@ -15,7 +15,7 @@ ms.assetid: e3086173-9eb5-4540-a23a-5d866bd05340 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 @@ -49,9 +49,9 @@ 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](../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](../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). @@ -59,22 +59,22 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnextc**|**_strnextc**|**_mbsnextc**|**_wcsnextc**| +|`_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](../using-generic-text-mappings.md) and [Generic-text mappings](../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 should not 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](../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**|\| +|**`_mbsnextc`**|\| +|**`_mbsnextc_l`**|\| +|**`_strnextc`**|\| +|**`_wcsnextc`**|\| For more compatibility information, see [Compatibility](../compatibility.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 d7d05ae5333..f74364cffef 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 @@ -15,7 +15,7 @@ ms.assetid: df6e5037-4039-4c85-a0a6-21d4ef513966 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 @@ -76,35 +76,35 @@ Indicates the relationship between the substrings, as follows. |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 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 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](../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). +**`_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](../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](../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 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| +|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**| +|`_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**|\| +|**`_strnicmp`**, **`_strnicmp_l`**|\| +|**`_wcsnicmp`**, **`_wcsnicmp_l`**|\ or \| +|**`_mbsnicmp`**, **`_mbsnicmp_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 1508b778ecd..dd3afd53f26 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 @@ -15,7 +15,7 @@ ms.assetid: abf0c569-725b-428d-9ff2-924f430104b4 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 @@ -76,31 +76,31 @@ Each of these functions returns a value indicating the relationship of the subst |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](../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 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](../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](../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 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| +|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**| +|`_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**|\| +|**`_strnicoll`**, **`_strnicoll_l`**|\| +|**`_wcsnicoll`**, **`_wcsnicoll_l`**|\ or \| +|**`_mbsnicoll`**, **`_mbsnicoll_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 66f6871af2c..4cefef9219a 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 @@ -15,7 +15,7 @@ ms.assetid: 6caace64-f9e4-48c0-afa8-ea51824ad723 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 @@ -52,32 +52,32 @@ Locale to use. ## 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsninc**|**_strninc**|**_mbsninc**|**_wcsninc**| +|`_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](../using-generic-text-mappings.md) and [Generic-text mappings](../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 should not 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](../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**|\| +|**`_mbsninc`**|\| +|**`_mbsninc_l`**|\| +|**`_strninc`**|\| +|**`_wcsninc`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/strnlen-strnlen-s.md b/docs/c-runtime-library/reference/strnlen-strnlen-s.md index 562904822b7..832519c7895 100644 --- a/docs/c-runtime-library/reference/strnlen-strnlen-s.md +++ b/docs/c-runtime-library/reference/strnlen-strnlen-s.md @@ -80,11 +80,11 @@ 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`** do not 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -96,9 +96,9 @@ By default, this function's global state is scoped to the application. To change |**`_tcscnlen`**|**`strnlen`**|**`_mbsnlen`**|**`wcsnlen`**| |**`_tcscnlen_l`**|**`strnlen`**|**`_mbsnlen_l`**|**`wcsnlen`**| -**`_mbsnlen`** and **`_mbstrnlen`** return the number of multibyte characters in a multibyte-character string. **`_mbsnlen`** recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it does not test for multibyte-character validity. **`_mbstrnlen`** tests for multibyte-character validity and recognizes multibyte-character sequences. If the string that's passed to **`_mbstrnlen`** contains an invalid multibyte character, **`errno`** is set to **`EILSEQ`**. +**`_mbsnlen`** and **`_mbstrnlen`** return the number of multibyte characters in a multibyte-character string. **`_mbsnlen`** recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it 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`. -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](../locale.md). +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](../locale.md). ## Requirements 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 bba8c763ded..c2b6b9f6d9b 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 @@ -15,7 +15,7 @@ ms.assetid: 9cf1b321-b5cb-4469-b285-4c07cfbd8813 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). ## Syntax @@ -82,15 +82,15 @@ Locale to use. 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](../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`* 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](../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. ## 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`*. -**_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. +**`_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; 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](../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](../locale.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). @@ -98,20 +98,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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnset_s**|**_strnset_s**|**_mbsnbset_s**|**_wcsnset_s**| -|**_tcsnset_s_l**|**_strnset_s_l**|**_mbsnbset_s_l**|**_wcsnset_s_l**| +|`_tcsnset_s`|**`_strnset_s`**|**`_mbsnbset_s`**|**`_wcsnset_s`**| +|`_tcsnset_s_l`|**`_strnset_s_l`**|**`_mbsnbset_s_l`**|**`_wcsnset_s_l`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strnset_s**|\| -|**_strnset_s_l**|\| -|**_wcsnset_s**|\ or \| -|**_wcsnset_s_l**|\| -|**_mbsnset_s**, **_mbsnset_s_l**|\| +|**`_strnset_s`**|\| +|**`_strnset_s_l`**|\| +|**`_wcsnset_s`**|\ or \| +|**`_wcsnset_s_l`**|\| +|**`_mbsnset_s`**, **`_mbsnset_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/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 44ecf851108..8de15a6afeb 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 @@ -15,7 +15,7 @@ ms.assetid: 3f306489-5763-48e5-b939-aefee7c94ef5 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 @@ -75,32 +75,32 @@ 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; those 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](../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`** do not 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](../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](../locale.md). By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnset**|**_strnset**|**_mbsnbset**|**_wcsnset**| -|**_tcsnset_l**|**_strnset_l**|**_mbsnbset_l**|**_wcsnset_l**| +|`_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**|\| +|**`_strnset`**|\| +|**`_strnset_l`**|\| +|**`_wcsnset`**|\ or \| +|**`_wcsnset_l`**|\| +|**`_mbsnset`**, **`_mbsnset_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 55a08ff2fbc..f1ffc38da3b 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 @@ -86,7 +86,7 @@ Locale to use. ## 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 @@ -94,19 +94,19 @@ The `strpbrk` function returns a pointer to the first occurrence of a 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. -`_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` 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` do not 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`](../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](../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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |`_tcspbrk`|`strpbrk`|`_mbspbrk`|`wcspbrk`| |**n/a**|**n/a**|`_mbspbrk_l`|**n/a**| 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 e2e6ea136cf..5148e420a44 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 @@ -103,7 +103,7 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |`_tcsrchr`|`strrchr`|`_mbsrchr`|`wcsrchr`| |**n/a**|**n/a**|`_mbsrchr_l`|**n/a**| 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 f2096803d3d..03c05478bf8 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 @@ -15,7 +15,7 @@ ms.assetid: 87863e89-4fa0-421c-af48-25d8516fe72f 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 @@ -49,11 +49,11 @@ Returns a pointer to the altered string. No return value is reserved to indicate ## 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; 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. -**_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** 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`** do not 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](../locale.md). +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](../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). @@ -62,18 +62,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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsrev**|**_strrev**|**_mbsrev**|**_wcsrev**| -|**n/a**|**n/a**|**_mbsrev_l**|**n/a**| +|`_tcsrev`|**`_strrev`**|**`_mbsrev`**|**`_wcsrev`**| +|**n/a**|**n/a**|**`_mbsrev_l`**|**n/a**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strrev**|\| -|**_wcsrev**|\ or \| -|**_mbsrev**, **_mbsrev_l**|\| +|**`_strrev`**|\| +|**`_wcsrev`**|\ or \| +|**`_mbsrev`**, **`_mbsrev_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 503971cdb25..e987e549174 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 @@ -15,7 +15,7 @@ ms.assetid: dceb2909-6b41-4792-acb7-888e45bb8b35 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 @@ -73,13 +73,13 @@ Locale to use. 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](../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 is not 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](../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](../locale.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). @@ -87,20 +87,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| +|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**| +|`_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**|\| +|**`_strset_s`**|\| +|**`_strset_s_l`**|\| +|**`_wcsset_s`**|\ or \| +|**`_wcsset_s_l`**|\| +|**`_mbsset_s`**, **`_mbsset_s_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 37ba1798a2f..c9bbb99a603 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 @@ -15,7 +15,7 @@ ms.assetid: c42ded42-2ed9-4f06-a0a9-247ba305473a 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 @@ -66,11 +66,11 @@ 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](../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`** do not 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](../locale.md). +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](../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). @@ -79,20 +79,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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsset**|**_strset**|**_mbsset**|**_wcsset**| -|**_tcsset_l**|**_strset_l**|**_mbsset_l**|**_wcsset_l**| +|`_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**|\| +|**`_strset`**|\| +|**`_strset_l`**|\| +|**`_wcsset`**|\ or \| +|**`_wcsset_l`**|\| +|**`_mbsset`**, **`_mbsset_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 5bc7ab23b59..5562056c588 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 @@ -15,7 +15,7 @@ ms.assetid: d077284a-809f-4068-959e-c6d6262677eb Returns the index of the first character, in a string, that does not belong to a 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 @@ -56,28 +56,28 @@ Returns an integer value specifying the length of the substring in *`str`* that ## 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 does not belong to the set of characters in *`strCharSet`*. The search does not 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](../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; 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](../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. -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](../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](../locale.md). By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsspn**|**strspn**|**_mbsspn**|**wcsspn**| -|**n/a**|**n/a**|**_mbsspn_l**|**n/a**| +|`_tcsspn`|**`strspn`**|**`_mbsspn`**|**`wcsspn`**| +|**n/a**|**n/a**|**`_mbsspn_l`**|**n/a**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**strspn**|\| -|**wcsspn**|\ or \| -|**_mbsspn**, **_mbsspn_l**|\| +|**`strspn`**|\| +|**`wcsspn`**|\ or \| +|**`_mbsspn`**, **`_mbsspn_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 f7ae0f0908c..f23f465389a 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 @@ -15,7 +15,7 @@ ms.assetid: 1ce18100-2edd-4c3b-af8b-53f204d80233 Returns a pointer to the first character in a given string that is not 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 @@ -52,33 +52,33 @@ Locale to use. ## 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 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. ## 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](../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 does not 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 does not 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](../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 behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|Tchar.h routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsspnp**|**_strspnp**|**_mbsspnp**|**_wcsspnp**| +|`_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](../using-generic-text-mappings.md) and [Generic-text mappings](../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 are provided only for this mapping and should not 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](../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**|\| +|**`_mbsspnp`**|\| +|**`_strspnp`**|\| +|**`_wcsspnp`**|\| For more compatibility information, see [Compatibility](../compatibility.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 6948e4f611b..02a46799a78 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 @@ -86,11 +86,11 @@ Locale to use. ## 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`* does not 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](../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 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](../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. > [!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). 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 2e04a0b9fa1..5e81bd8407a 100644 --- a/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md +++ b/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md @@ -53,22 +53,22 @@ If an error condition occurs, the invalid parameter handler is invoked, as descr |*`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| +|`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 -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. ## 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 *`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 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 past 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](../secure-template-overloads.md). @@ -78,16 +78,16 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrtime_s**|**_strtime_s**|**_strtime_s**|**_wstrtime_s**| +|`_tstrtime_s`|**`_strtime_s`**|**`_strtime_s`**|**`_wstrtime_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strtime_s**|\| -|**_wstrtime_s**|\ or \| +|**`_strtime_s`**|\| +|**`_wstrtime_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/strtime-wstrtime.md b/docs/c-runtime-library/reference/strtime-wstrtime.md index 5aad3f4de2c..e09833136cb 100644 --- a/docs/c-runtime-library/reference/strtime-wstrtime.md +++ b/docs/c-runtime-library/reference/strtime-wstrtime.md @@ -44,9 +44,9 @@ 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 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. -**_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. +**`_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](../secure-template-overloads.md). @@ -54,16 +54,16 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrtime**|**_strtime**|**_strtime**|**_wstrtime**| +|`_tstrtime`|**`_strtime`**|**`_strtime`**|**`_wstrtime`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_strtime**|\| -|**_wstrtime**|\ or \| +|**`_strtime`**|\| +|**`_wstrtime`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 e5c0b50871b..b064807de3c 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 @@ -49,12 +49,12 @@ The locale to use. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -66,14 +66,14 @@ 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| +|`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](../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: 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 2ac12f9cadd..41adbf957b0 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 @@ -50,30 +50,30 @@ The locale to use. ## 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 cannot 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](../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`](../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 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. By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstof**|**strtof**|**strtof**|**wcstof**| -|**_tcstof_l**|**_strtof_l**|**_strtof_l**|**_wcstof_l**| +|`_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](../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`* 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`*. -**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`*] @@ -85,8 +85,8 @@ The UCRT versions of these functions do not support conversion of Fortran-style |Routine|Required header| |-------------|---------------------| -|**strtof**, **_strtof_l**|C: \ C++: \ or \| -|**wcstof**, **_wcstof_l**|C: \ or \ C++: \, \ or \| +|**`strtof`**, **`_strtof_l`**|C: \ C++: \ or \| +|**`wcstof`**, **`_wcstof_l`**|C: \ or \ C++: \, \ or \| For more compatibility information, see [Compatibility](../compatibility.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 e2c4d067cc8..6ad6c3a4f33 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 @@ -57,11 +57,11 @@ 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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -78,9 +78,9 @@ By default, this function's global state is scoped to the application. To change |**`_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](../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: 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 80c6da844c4..e2ac7ac0de0 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 @@ -57,30 +57,30 @@ The locale to use. ## 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`](../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 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 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). +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`* 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`*. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoimax**|**strtoimax**|**strtoimax**|**wcstoimax**| -|**_tcstoimax_l**|**strtoimax_l**|**_strtoimax_l**|**_wcstoimax_l**| +|`_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`*] @@ -90,7 +90,7 @@ A *`whitespace`* may consist of space and tab characters, which are ignored; *`d |Routine|Required header| |-------------|---------------------| -|**strtoimax**, **_strtoimax_l**, **wcstoimax**, **_wcstoimax_l**|\| +|**`strtoimax`**, **`_strtoimax_l`**, **`wcstoimax`**, **`_wcstoimax_l`**|\| For more compatibility information, see [Compatibility](../compatibility.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 e6e01ae5ee5..1e40d84eb21 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 @@ -76,29 +76,29 @@ The locale to use. ## 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 -|*`str`*|*`delimiters`*|*`context`*|Return value|**`errno`**| +|*`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`**| +|`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. -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`**. +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](../locale.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 05ab6b8bbdc..1dd971e0c26 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 @@ -70,7 +70,7 @@ Points to memory used to store the internal state of the parser so that the pars ## 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 @@ -81,9 +81,9 @@ The two argument version of **`wcstok`** is not standard. If you need to use tha > [!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). -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](../locale.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 6188c32f050..99dc25be6df 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 @@ -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. @@ -57,17 +57,17 @@ Locale to use. ## 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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../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](../locale.md). +**`wcstol`** and **`_wcstol_l`** are wide-character versions of **`strtol`** and **`_strtol_l`**. Their *`string`* argument is a wide-character string. These functions behave identically to **`strtol`** and **`_strtol_l`** otherwise. The locale's `LC_NUMERIC` category setting determines recognition of the radix character (the fractional marker or decimal point) in *`string`*. The functions **`strtol`** and **`wcstol`** use the current locale. **`_strtol_l`** and **`_wcstol_l`** use the locale passed in instead. For more information, see [`setlocale`] and [Locale](../locale.md). -When *`end_ptr`* is **`NULL`**, it's ignored. Otherwise, a pointer to the character that stopped the scan is stored at the location pointed to by *`end_ptr`*. No conversion is possible if no valid digits are found, or an invalid base is specified. The value of *`string`* is then stored at the location pointed to by *`end_ptr`*. +When *`end_ptr`* is `NULL`, it's ignored. Otherwise, a pointer to the character that stopped the scan is stored at the location pointed to by *`end_ptr`*. No conversion is possible if no valid digits are found, or an invalid base is specified. The value of *`string`* is then stored at the location pointed to by *`end_ptr`*. **`strtol`** expects *`string`* to point to a string of the following form: @@ -79,7 +79,7 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_tcstol`**|**`strtol`**|**`strtol`**|**`wcstol`**| |**`_tcstol_l`**|**`_strtol_l`**|**`_strtol_l`**|**`_wcstol_l`**| diff --git a/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md b/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md index 0f587787bdf..6595a1e890c 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 @@ -49,30 +49,30 @@ The locale to use. ## 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 cannot 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](../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`](../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 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. By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstold**|**strtold**|**strtold**|**wcstold**| -|**_tcstold_l**|**_strtold_l**|**_strtold_l**|**_wcstold_l**| +|`_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](../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`* 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`*. -**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`*] @@ -82,8 +82,8 @@ A *`whitespace`* may consist of space and tab characters, which are ignored; *`s |Routine|Required header| |-------------|---------------------| -|**strtold**, **_strtold_l**|\| -|**wcstold**, **_wcstold_l**|\ or \| +|**`strtold`**, **`_strtold_l`**|\| +|**`wcstold`**, **`_wcstold_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 71ac53f9d8e..48d742d3781 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 @@ -57,32 +57,32 @@ The locale to use. ## 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`](../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 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. By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoll**|**strtoll**|**strtoll**|**wcstoll**| -|**_tcstoll_l**|**_strtoll_l**|**_strtoll_l**|**_wcstoll_l**| +|`_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](../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`* 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`*. -**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`*] @@ -92,8 +92,8 @@ A *`whitespace`* may consist of space and tab characters, which are ignored; *`d |Routine|Required header| |-------------|---------------------| -|**strtoll**, **_strtoll_l**|\| -|**wcstoll**, **_wcstoll_l**|\ or \| +|**`strtoll`**, **`_strtoll_l`**|\| +|**`wcstoll`**, **`_wcstoll_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 1fd9cc191eb..a46a60da2b2 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 @@ -57,11 +57,11 @@ 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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -80,9 +80,9 @@ By default, this function's global state is scoped to the application. To change |**`_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](../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: 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 5c04ce7b8bd..4a1566aba69 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 @@ -56,7 +56,7 @@ Locale to use. ## 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. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -64,9 +64,9 @@ For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlis 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 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). +**`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. @@ -74,7 +74,7 @@ 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| +|`TCHAR.H` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| |**`_tcstoul`**|**`strtoul`**|**`strtoul`**|**`wcstoul`**| |**`_tcstoul_l`**|**`strtoul_l`**|**`_strtoul_l`**|**`_wcstoul_l`**| diff --git a/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md b/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md index 7062a1c7093..141979b4115 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 @@ -57,7 +57,7 @@ Locale to use. ## 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`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -65,35 +65,35 @@ For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlis 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](../locale.md). +**`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](../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`* 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`*. -**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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoull**|**strtoull**|**strtoull**|**wcstoull**| -|**_tcstoull_l**|**strtoull_l**|**_strtoull_l**|**_wcstoull_l**| +|`_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`*] -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 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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**strtoull**|\| -|**wcstoull**|\ or \| -|**_strtoull_l**|\| -|**_wcstoull_l**|\ or \| +|**`strtoull`**|\| +|**`wcstoull`**|\ or \| +|**`_strtoull_l`**|\| +|**`_wcstoull_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 cd1cf803716..646b1b5ff64 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 @@ -57,41 +57,41 @@ Locale to use. ## 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`](../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](../locale.md). +**`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](../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`* 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`*. -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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoumax**|**strtoumax**|**strtoumax**|**wcstoumax**| -|**_tcstoumax_l**|**strtoumax_l**|**_strtoumax_l**|**_wcstoumax_l**| +|`_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`*] -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 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. ## Requirements |Routine|Required header| |-------------|---------------------| -|**strtoumax**|\| -|**wcstoumax**|\ or \| -|**_strtoumax_l**|\| -|**_wcstoumax_l**|\ or \| +|**`strtoumax`**|\| +|**`wcstoumax`**|\ or \| +|**`_strtoumax_l`**|\| +|**`_wcstoumax_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md b/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md index cae9d8b7295..6f6147fffd9 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 @@ -15,7 +15,7 @@ ms.assetid: 82d3a273-9f6f-4a26-9560-919d891e4581 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 @@ -91,13 +91,13 @@ The locale to use. 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](../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](../locale.md). +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](../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](../secure-template-overloads.md). @@ -107,17 +107,17 @@ 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| +|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**| +|`_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 \| +|**`_strupr_s`**, **`_strupr_s_l`**|\| +|**`_wcsupr_s`**, **`_wcsupr_s_l`**, **`_mbsupr_s`**, **`_mbsupr_s_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 d7ce383352f..cf61d033200 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 @@ -15,7 +15,7 @@ ms.assetid: caac8f16-c233-41b6-91ce-575ec7061b77 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 @@ -84,11 +84,11 @@ Returns a pointer to the altered string. Because the modification is done in pla ## 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](../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 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](../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; those 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](../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](../secure-template-overloads.md). @@ -96,18 +96,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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsupr**|**_strupr**|**_mbsupr**|**_wcsupr**| -|**_tcsupr_l**|**_strupr_l**|**_mbsupr_l**|**_wcsupr_l**| +|`_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**|\| +|**`_strupr`**, **`_strupr_l`**|\| +|**`_wcsupr`**, **`_wcsupr_l`**|\ or \| +|**`_mbsupr`**, **`_mbsupr_l`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 38b37d19a34..55633a59ada 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 @@ -57,38 +57,38 @@ The locale to use. ## 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](../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 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. -**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 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. -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**. +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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsxfrm**|**strxfrm**|**strxfrm**|**wcsxfrm**| -|**_tcsxfrm_l**|**_strxfrm_l**|**_strxfrm_l**|**_wcsxfrm_l**| +|`_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: ```C strncpy( _string1, _string2, _count ); @@ -99,10 +99,10 @@ return( strlen( _string1 ) ); |Routine|Required header| |-------------|---------------------| -|**strxfrm**|\| -|**wcsxfrm**|\ or \| -|**_strxfrm_l**|\| -|**_wcsxfrm_l**|\ or \| +|**`strxfrm`**|\| +|**`wcsxfrm`**|\ or \| +|**`_strxfrm_l`**|\| +|**`_wcsxfrm_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/swab.md b/docs/c-runtime-library/reference/swab.md index aabf7274bf4..67cd9177b63 100644 --- a/docs/c-runtime-library/reference/swab.md +++ b/docs/c-runtime-library/reference/swab.md @@ -37,13 +37,13 @@ Number of bytes to be copied and swapped. ## Return value -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). +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). 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 isn't 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 behavior, see [Global state in the CRT](../global-state.md). @@ -51,7 +51,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_swab**|C: \ C++: \ or \| +|**`_swab`**|C: \ C++: \ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/system-wsystem.md b/docs/c-runtime-library/reference/system-wsystem.md index 62f85ba2d07..af8161f36b7 100644 --- a/docs/c-runtime-library/reference/system-wsystem.md +++ b/docs/c-runtime-library/reference/system-wsystem.md @@ -35,20 +35,20 @@ The command to be executed. ## Return value -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: +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 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 process that's making the call wasn't 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 process that's making the call wasn't allocated correctly. | 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`**. diff --git a/docs/c-runtime-library/reference/tan-tanf-tanl.md b/docs/c-runtime-library/reference/tan-tanf-tanl.md index 42e6dd15222..5934f4a4f53 100644 --- a/docs/c-runtime-library/reference/tan-tanf-tanl.md +++ b/docs/c-runtime-library/reference/tan-tanf-tanl.md @@ -37,10 +37,10 @@ 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| +|Input|SEH exception|`Matherr` exception| |-----------|-------------------|-------------------------| |`± QNAN`,`IND`|none|`_DOMAIN`| -|`± INF`|**INVALID**|`_DOMAIN`| +|`± INF`|`INVALID`|`_DOMAIN`| ## Remarks diff --git a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md index fddaec4a733..9b637367089 100644 --- a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md +++ b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md @@ -36,7 +36,7 @@ Angle in radians. The **`tanh`** functions return the hyperbolic tangent of *`x`*. There's no error return. -|Input|SEH exception|**`Matherr`** exception| +|Input|SEH exception|`Matherr` exception| |-----------|-------------------|-------------------------| |± `QNAN`,`IND`|none|`_DOMAIN`| diff --git a/docs/c-runtime-library/reference/tell-telli64.md b/docs/c-runtime-library/reference/tell-telli64.md index af3fbb98b4a..93d94fd4542 100644 --- a/docs/c-runtime-library/reference/tell-telli64.md +++ b/docs/c-runtime-library/reference/tell-telli64.md @@ -34,13 +34,13 @@ File descriptor referring to open file. 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](../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. 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 behavior, see [Global state in the CRT](../global-state.md). @@ -48,7 +48,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_tell**, **_telli64**|\| +|**`_tell`**, **`_telli64`**|\| For more compatibility information, see [Compatibility](../compatibility.md). 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 ee26178f247..bf9f63998e7 100644 --- a/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md +++ b/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md @@ -12,7 +12,7 @@ ms.assetid: e3760bb4-bb01-4808-b689-2c45af56a170 --- # `_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 @@ -39,41 +39,41 @@ wchar_t *_wtempnam_dbg( The path used in the file name if there is no TMP environment variable, or if TMP is not a valid directory. *`prefix`*\ -The string that will be pre-pended to names returned by **_tempnam**. +The string that will be pre-pended to names returned by `_tempnam`. *`blockType`*\ -Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. *`filename`*\ -Pointer to name of source file that requested allocation operation or **NULL**. +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**. +Line number in source file where allocation operation was requested or `NULL`. ## 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 is a failure. Failure can occur if there is 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 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). ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ttempnam_dbg**|**_tempnam_dbg**|**_tempnam_dbg**|**_wtempnam_dbg**| +|`_ttempnam_dbg`|**`_tempnam_dbg`**|**`_tempnam_dbg`**|**`_wtempnam_dbg`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_tempnam_dbg**, **_wtempnam_dbg**|\| +|**`_tempnam_dbg`**, **`_wtempnam_dbg`**|\| For more compatibility information, see [Compatibility](../compatibility.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 b688a128e13..0a55234bb01 100644 --- a/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md +++ b/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md @@ -36,7 +36,7 @@ wchar_t *_wtmpnam( ### Parameters *`prefix`*\ -The string that will be pre-pended to names returned by **_tempnam**. +The string that will be pre-pended 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. @@ -46,45 +46,45 @@ Pointer that will hold the generated name and will be identical to the name retu ## 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 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. > [!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 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. -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`** will generate 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 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 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 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 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. -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`** 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. -**_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`** 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. -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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ttmpnam**|**tmpnam**|**tmpnam**|**_wtmpnam**| -|**_ttempnam**|**_tempnam**|**_tempnam**|**_wtempnam**| +|`_ttmpnam`|**`tmpnam`**|**`tmpnam`**|**`_wtmpnam`**| +|`_ttempnam`|**`_tempnam`**|**`_tempnam`**|**`_wtempnam`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_tempnam**|\| -|**_wtempnam**, **_wtmpnam**|\ or \| -|**tmpnam**|\| +|**`_tempnam`**|\| +|**`_wtempnam`**, **`_wtmpnam`**|\ or \| +|**`tmpnam`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/terminate-crt.md b/docs/c-runtime-library/reference/terminate-crt.md index bd68c0dbd4d..40b549f5bd4 100644 --- a/docs/c-runtime-library/reference/terminate-crt.md +++ b/docs/c-runtime-library/reference/terminate-crt.md @@ -12,7 +12,7 @@ ms.assetid: 90e67402-08e9-4b2a-962c-66a8afd3ccb4 --- # `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,7 +22,7 @@ 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. @@ -30,7 +30,7 @@ The **terminate** function is used with C++ exception handling and is called in - 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 behavior, see [Global state in the CRT](../global-state.md). @@ -38,7 +38,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**terminate**|\| +|**`terminate`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md index ddf87980b84..c5770a03061 100644 --- a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md +++ b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md @@ -67,7 +67,7 @@ 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](../tgmath.md) for details. @@ -79,8 +79,8 @@ By default, this function's global state is scoped to the application. To change |Function|C header|C++ header| |--------------|--------------|------------------| -|**tgamma**, **tgammaf**, **tgammal**|\|\| -|**tgamma** macro | \ || +|**`tgamma`**, **`tgammaf`**, **`tgammal`**|\|\| +|**`tgamma`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/time-time32-time64.md b/docs/c-runtime-library/reference/time-time32-time64.md index 782e7c59ec0..bf1dad18129 100644 --- a/docs/c-runtime-library/reference/time-time32-time64.md +++ b/docs/c-runtime-library/reference/time-time32-time64.md @@ -33,9 +33,9 @@ Returns the time as seconds elapsed since midnight, January 1, 1970, or -1 in th ## 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 is not stored. -**`time`** is a wrapper for **`_time64`** and **`time_t`** is, by default, equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. This is not recommended because your application may fail after January 18, 2038; the use of this macro is not allowed on 64-bit platforms. +**`time`** is a wrapper for **`_time64`** and **`time_t`** is, by default, equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`. 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. ## Requirements 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 ede42c00ffb..23132cba515 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 @@ -45,11 +45,11 @@ 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. 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`**. **End Microsoft Specific** @@ -59,7 +59,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**timespec_get**, **_timespec32_get**, **_timespec64_get**|C: \, C++: \ or \| +|**`timespec_get`**, **`_timespec32_get`**, **`_timespec64_get`**|C: \, C++: \ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/tmpfile-s.md b/docs/c-runtime-library/reference/tmpfile-s.md index 915dab7c514..0c282c78bf3 100644 --- a/docs/c-runtime-library/reference/tmpfile-s.md +++ b/docs/c-runtime-library/reference/tmpfile-s.md @@ -35,17 +35,17 @@ Returns 0 if successful, an error code on failure. |*`pFilePtr`*|Return value|Contents of *`pFilePtr`*| |----------------|----------------------|---------------------------------| -|**NULL**|**EINVAL**|not changed| +|`NULL`|`EINVAL`|not changed| -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**. +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) in conjunction 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 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. -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 behavior, see [Global state in the CRT](../global-state.md). @@ -53,7 +53,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**tmpfile_s**|\| +|**`tmpfile_s`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/tmpfile.md b/docs/c-runtime-library/reference/tmpfile.md index 0038b34026e..346a04da24f 100644 --- a/docs/c-runtime-library/reference/tmpfile.md +++ b/docs/c-runtime-library/reference/tmpfile.md @@ -22,21 +22,21 @@ FILE *tmpfile( void ); ## 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) in conjunction 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 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. -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**|\| +|**`tmpfile`**|\| For more compatibility information, see [Compatibility](../compatibility.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 855054aa5a9..f882ea1840b 100644 --- a/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md +++ b/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md @@ -51,18 +51,18 @@ Both of these functions return 0 if successful or an error number on failure. | *`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](../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 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. -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`** does not 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](../secure-template-overloads.md). @@ -70,16 +70,16 @@ 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ttmpnam_s**|**tmpnam_s**|**tmpnam_s**|**_wtmpnam_s**| +|`_ttmpnam_s`|**`tmpnam_s`**|**`tmpnam_s`**|**`_wtmpnam_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**tmpnam_s**|\| -|**_wtmpnam_s**|\ or \| +|**`tmpnam_s`**|\| +|**`_wtmpnam_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/toascii-toascii.md b/docs/c-runtime-library/reference/toascii-toascii.md index 68911e482d5..315dbdac25c 100644 --- a/docs/c-runtime-library/reference/toascii-toascii.md +++ b/docs/c-runtime-library/reference/toascii-toascii.md @@ -30,21 +30,21 @@ Character to convert. ## 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 is 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) is not defined or is defined as 0; otherwise it is undefined. ## Requirements |Routine|Required header| |-------------|---------------------| -|**toascii**, **__toascii**|C: \

C++: \ or \| +|**`toascii`**, **`__toascii`**|C: \

C++: \ or \| -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). +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 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 898b3126883..f744b523666 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 @@ -50,29 +50,29 @@ Each of these routines converts a copy of *`c`* to lower case if the conversion ## 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](../locale.md). +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](../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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_totlower**|**tolower**|**_mbctolower**|**towlower**| -|**_totlower_l**|**_tolower_l**|**_mbctolower_l**|**_towlower_l**| +|`_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 \| +|**`tolower`**|\| +|**`_tolower`**|\| +|**`towlower`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 137c6a23603..9401654e714 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 @@ -48,37 +48,37 @@ Locale to use. 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 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. 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. +In order for **`toupper`** to give the expected results, [`__isascii`](isascii-isascii-iswascii.md) and [`islower`](islower-iswlower-islower-l-iswlower-l.md) must both return nonzero. ## Remarks -Each of these routines converts a given lowercase letter to an uppercase letter if possible and appropriate. The case conversion of **towupper** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the **_l** suffix use the currently set locale. The versions of these functions with the **_l** suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). +Each of these routines converts a given lowercase letter to an uppercase letter if possible and appropriate. The case conversion of **`towupper`** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the `_l` suffix use the currently set locale. The versions of these functions with the `_l` suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). -In order for **toupper** to give the expected results, [`__isascii`](isascii-isascii-iswascii.md) and [`isupper`](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. +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. By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_totupper**|**toupper**|**_mbctoupper**|**towupper**| -|**_totupper_l**|**_toupper_l**|**_mbctoupper_l**|**_towupper_l**| +|`_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 \| +|**`toupper`**|\| +|**`_toupper`**|\| +|**`towupper`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/towctrans.md b/docs/c-runtime-library/reference/towctrans.md index 0f4e3d818a7..9ab1848012b 100644 --- a/docs/c-runtime-library/reference/towctrans.md +++ b/docs/c-runtime-library/reference/towctrans.md @@ -33,7 +33,7 @@ An identifier that contains the return value of [`wctrans`](wctrans.md). ## 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 @@ -43,13 +43,13 @@ The value of *`category`* must have been returned by an earlier successful call |Routine|Required header| |-------------|---------------------| -|**towctrans**|\| +|**`towctrans`**|\| 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 diff --git a/docs/c-runtime-library/reference/trunc-truncf-truncl.md b/docs/c-runtime-library/reference/trunc-truncf-truncl.md index 888d449a825..67e2ef66d19 100644 --- a/docs/c-runtime-library/reference/trunc-truncf-truncl.md +++ b/docs/c-runtime-library/reference/trunc-truncf-truncl.md @@ -46,7 +46,7 @@ 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](../tgmath.md) for details. @@ -58,8 +58,8 @@ You can also round down by implicitly converting from floating-point to integral |Function|C header|C++ header| |--------------|--------------|------------------| -|**trunc**, **truncf**, **truncl**|\|\| -|**trunc** macro | \ || +|**`trunc`**, **`truncf`**, **`truncl`**|\|\| +|**`trunc`** macro | \ || For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/tzset.md b/docs/c-runtime-library/reference/tzset.md index bf30f8bf0c8..a4e39ac0cea 100644 --- a/docs/c-runtime-library/reference/tzset.md +++ b/docs/c-runtime-library/reference/tzset.md @@ -25,7 +25,7 @@ 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`*] @@ -42,29 +42,29 @@ The **_tzset** function uses the current setting of the environment variable **T 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). + 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 the following 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. -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 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. -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| +|`_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| -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 behavior, see [Global state in the CRT](../global-state.md). @@ -72,9 +72,9 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_tzset**|\| +|**`_tzset`**|\| -The **_tzset** function is Microsoft-specific. For more information, see [Compatibility](../compatibility.md). +The **`_tzset`** function is Microsoft-specific. For more information, see [Compatibility](../compatibility.md). ## Example diff --git a/docs/c-runtime-library/reference/umask-s.md b/docs/c-runtime-library/reference/umask-s.md index 5ccafbc11ed..6293ebad4ab 100644 --- a/docs/c-runtime-library/reference/umask-s.md +++ b/docs/c-runtime-library/reference/umask-s.md @@ -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](../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. diff --git a/docs/c-runtime-library/reference/umask.md b/docs/c-runtime-library/reference/umask.md index 7803ffec187..fe5004e00ea 100644 --- a/docs/c-runtime-library/reference/umask.md +++ b/docs/c-runtime-library/reference/umask.md @@ -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. 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 8c68466cd0a..1002d96ae55 100644 --- a/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md +++ b/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md @@ -33,32 +33,32 @@ wint_t _ungetwc_nolock( Character to be pushed. *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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`* 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`. 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 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. By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettc_nolock**|**_ungetc_nolock**|**_ungetc_nolock**|**_ungetwc_nolock**| +|`_ungettc_nolock`|**`_ungetc_nolock`**|**`_ungetc_nolock`**|**`_ungetwc_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_ungetc_nolock**|\| -|**_ungetwc_nolock**|\ or \| +|**`_ungetc_nolock`**|\| +|**`_ungetwc_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/ungetc-ungetwc.md b/docs/c-runtime-library/reference/ungetc-ungetwc.md index e6f20aa8421..7e0ef9728e6 100644 --- a/docs/c-runtime-library/reference/ungetc-ungetwc.md +++ b/docs/c-runtime-library/reference/ungetc-ungetwc.md @@ -33,23 +33,23 @@ wint_t ungetwc( Character to be pushed. *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. ## 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](../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`* 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](../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 [`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. This is 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). @@ -57,18 +57,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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettc**|**ungetc**|**ungetc**|**ungetwc**| +|`_ungettc`|**`ungetc`**|**`ungetc`**|**`ungetwc`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**ungetc**|\| -|**ungetwc**|\ or \| +|**`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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Example 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 5d7a1d6d75a..f2ba106b2b4 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 @@ -41,29 +41,29 @@ Character to be pushed. ## 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 is 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 are 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 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. By default, this function's 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettch**|**_ungetch**|**_ungetch**|**_ungetwch**| -|**_ungettch_nolock**|**_ungetch_nolock**|**_ungetch_nolock**|**_ungetwch_nolock**| +|`_ungettch`|**`_ungetch`**|**`_ungetch`**|**`_ungetwch`**| +|`_ungettch_nolock`|**`_ungetch_nolock`**|**`_ungetch_nolock`**|**`_ungetwch_nolock`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_ungetch**, **_ungetch_nolock**|\| -|**_ungetwch**, **_ungetwch_nolock**|\ or \| +|**`_ungetch`**, **`_ungetch_nolock`**|\| +|**`_ungetwch`**, **`_ungetwch_nolock`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/unlink-wunlink.md b/docs/c-runtime-library/reference/unlink-wunlink.md index d7d9b828e5b..2c9ae7688db 100644 --- a/docs/c-runtime-library/reference/unlink-wunlink.md +++ b/docs/c-runtime-library/reference/unlink-wunlink.md @@ -32,28 +32,28 @@ Name of file to remove. ## 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 isn't 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. 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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tunlink**|**_unlink**|**_unlink**|**_wunlink**| +|`_tunlink`|**`_unlink`**|**`_unlink`**|**`_wunlink`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_unlink**|\ and \| -|**_wunlink**|\ or \| +|**`_unlink`**|\ and \| +|**`_wunlink`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/unlock-file.md b/docs/c-runtime-library/reference/unlock-file.md index c4d9f15600d..92550accb30 100644 --- a/docs/c-runtime-library/reference/unlock-file.md +++ b/docs/c-runtime-library/reference/unlock-file.md @@ -29,7 +29,7 @@ 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 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). By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). @@ -37,7 +37,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**_unlock_file**|\| +|**`_unlock_file`**|\| For more compatibility information, see [Compatibility](../compatibility.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 0206c20b98b..77f590c0247 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 @@ -53,59 +53,59 @@ Pointer to stored time values. ## 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](../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 | +| `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 | 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 | -Specific versions of the **_utimbuf** structure (**_utimebuf32** and **__utimbuf64**) are defined using the 32-bit and 64-bit versions of the time type. These structures are used in the 32-bit and 64-bit specific versions of this function. **_utimbuf** itself by default uses a 64-bit time type unless **_USE_32BIT_TIME_T** is defined. +Specific versions of the `_utimbuf` structure (`_utimebuf32` and `__utimbuf64`) are defined using the 32-bit and 64-bit versions of the time type. These structures are used in the 32-bit and 64-bit specific versions of this function. `_utimbuf` itself by default uses a 64-bit time type unless `_USE_32BIT_TIME_T` is defined. -**_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 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| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_tutime**|**_utime**|**_utime**|**_wutime**| -|**_tutime32**|**_utime32**|**_utime32**|**_wutime32**| -|**_tutime64**|**_utime64**|**_utime64**|**_wutime64**| +|`_tutime`|**`_utime`**|**`_utime`**|**`_wutime`**| +|`_tutime32`|**`_utime32`**|**`_utime32`**|**`_wutime32`**| +|`_tutime64`|**`_utime64`**|**`_utime64`**|**`_wutime64`**| ## Requirements |Routine|Required headers|Optional headers| |-------------|----------------------|----------------------| -|**_utime**, **_utime32**, **_utime64**|\|\| -|**_utime64**|\|\| -|**_wutime**|\ or \|\| +|**`_utime`**, **`_utime32`**, **`_utime64`**|\|\| +|**`_utime64`**|\|\| +|**`_wutime`**|\ or \|\| 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 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 d27d58d6c35..f8df1c1d1a3 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 @@ -72,7 +72,7 @@ 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. @@ -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 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 3d8dc12692c..1c5970d4dbf 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 @@ -54,13 +54,13 @@ For more information, see [Format specification syntax: `printf` and `wprintf` f ## 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](../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](../printf-p-positional-parameters.md). @@ -69,21 +69,21 @@ These functions do not translate line-feed characters into carriage return-line > [!IMPORTANT] > 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](../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 -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \| +|**`_vcprintf_p`**, **`_vcprintf_p_l`**|\ and \| +|**`_vcwprintf_p`**, **`_vcwprintf_p_l`**|\ and \| For more compatibility information, see [Compatibility](../compatibility.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 bd7c3b55fcb..4e858702274 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 @@ -56,30 +56,30 @@ For more information, see [Format specification syntax: `printf` and `wprintf` f 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](../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`* 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. ## 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). ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vtcprintf_s**|**_vcprintf_s**|**_vcprintf_s**|**_vcwprintf_s**| -|**_vtcprintf_s_l**|**_vcprintf_s_l**|**_vcprintf_s_l**|**_vcwprintf_s_l**| +|`_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 \|\*| +|**`_vcprintf_s`**, **`_vcprintf_s_l`**|\ and \|\*| +|**`_vcwprintf_s`**, **`_vcwprintf_s_l`**|\ or \, and \|\*| \* Required for UNIX V compatibility. 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 8e28d99ed91..417e8cf72db 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 @@ -54,13 +54,13 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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). @@ -69,17 +69,17 @@ The versions of these functions with the **_l** suffix are identical except that ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vtcprintf**|**_vcprintf**|**_vcprintf**|**_vcwprintf**| -|**_vtcprintf_l**|**_vcprintf_l**|**_vcprintf_l**|**_vcwprintf_l**| +|`_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 \|\*| +|**`_vcprintf`**, **`_vcprintf_l`**|\ and \|\*| +|**`_vcwprintf`**, **`_vcwprintf_l`**|\ or \, and \|\*| \* Required for UNIX V compatibility. 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 5199d7fe00d..2d44a5aad95 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 @@ -43,7 +43,7 @@ int _vfwprintf_p_l( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`format`*\ Format specification. @@ -58,35 +58,35 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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). -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**. +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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \|\*| +|**`_vfprintf_p`**, **`_vfprintf_p_l`**|\ and \|\*| +|**`_vfwprintf_p`**, **`_vfwprintf_p_l`**|\ or \, and \|\*| \* Required for UNIX V compatibility. 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 57d4f92cd33..26536bc3697 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 @@ -43,7 +43,7 @@ int _vfwprintf_s_l( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`format`*\ Format specification. @@ -58,7 +58,7 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -68,9 +68,9 @@ Each of these functions takes a pointer to an argument list, then formats and wr 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). @@ -78,17 +78,17 @@ The versions of these functions with the **_l** suffix are identical except that ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf_s**|**vfprintf_s**|**vfprintf_s**|**vfwprintf_s**| -|**_vftprintf_s_l**|**_vfprintf_s_l**|**_vfprintf_s_l**|**_vfwprintf_s_l**| +|`_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 \|\*| +|**`vfprintf_s`**, **`_vfprintf_s_l`**|\ and \|\*| +|**`vfwprintf_s`**, **`_vfwprintf_s_l`**|\ or \, and \|\*| \* Required for UNIX V compatibility. 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 4b09383203a..a600b41703a 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 @@ -43,7 +43,7 @@ int _vfwprintf_l( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`format`*\ Format specification. @@ -58,7 +58,7 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -66,9 +66,9 @@ For information on these and other error codes, see [`errno`, `_doserrno`, `_sys 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). @@ -76,17 +76,17 @@ The versions of these functions with the **_l** suffix are identical except that ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf**|**vfprintf**|**vfprintf**|**vfwprintf**| -|**_vftprintf_l**|**_vfprintf_l**|**_vfprintf_l**|**_vfwprintf_l**| +|`_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 \|\*| +|**`vfprintf`**, **`_vfprintf_l`**|\ and \|\*| +|**`vfwprintf`**, **`_vfwprintf_l`**|\ or \, and \|\*| \* Required for UNIX V compatibility. 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 63b3eb1acfa..4f5ec4ae6b5 100644 --- a/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md +++ b/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md @@ -31,7 +31,7 @@ int vfwscanf_s( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`format`*\ Format-control string. @@ -41,31 +41,31 @@ Variable argument list. ## 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 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`**. -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**. +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](../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](../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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vftscanf_s**|**vfscanf_s**|**vfscanf_s**|**vfwscanf_s**| +|`_vftscanf_s`|**`vfscanf_s`**|**`vfscanf_s`**|**`vfwscanf_s`**| ## Requirements |Function|Required header| |--------------|---------------------| -|**vfscanf_s**|\| -|**vfwscanf_s**|\ or \| +|**`vfscanf_s`**|\| +|**`vfwscanf_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md index 57b66cacc79..959b9b93f1e 100644 --- a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md +++ b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md @@ -31,7 +31,7 @@ int vfwscanf( ### Parameters *`stream`*\ -Pointer to **FILE** structure. +Pointer to `FILE` structure. *`format`*\ Format-control string. @@ -41,21 +41,21 @@ Variable argument list. ## 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 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`**. -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**. +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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vftscanf**|**vfscanf**|**vfscanf**|**vfwscanf**| +|`_vftscanf`|**`vfscanf`**|**`vfscanf`**|**`vfwscanf`**| For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). @@ -63,8 +63,8 @@ For more information, see [Format specification fields: `scanf` and `wscanf` fun |Function|Required header| |--------------|---------------------| -|**vfscanf**|\| -|**vfwscanf**|\ or \| +|**`vfscanf`**|\| +|**`vfwscanf`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 fc7e2cd11ab..ebacf778e06 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 @@ -51,39 +51,39 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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). -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**. +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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \|\*| +|**`_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 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 more compatibility information, see [Compatibility](../compatibility.md). ## See also 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 832cc04e57a..bd5750f6eab 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 @@ -51,19 +51,19 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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 [`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). @@ -71,21 +71,21 @@ The versions of these functions with the **_l** suffix are identical except that ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf_s**|**vprintf_s**|**vprintf_s**|**vwprintf_s**| -|**_vtprintf_s_l**|**_vprintf_s_l**|**_vprintf_s_l**|**_vwprintf_s_l**| +|`_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 \|\*| +|**`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 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 more compatibility information, see [Compatibility](../compatibility.md). ## See also 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 664f1b83a35..951169dda08 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 @@ -51,17 +51,17 @@ For more information, see [Format specification syntax](../format-specification- ## 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](../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 [`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. @@ -69,21 +69,21 @@ The versions of these functions with the **_l** suffix are identical except that ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf**|**vprintf**|**vprintf**|**vwprintf**| -|**_vtprintf_l**|**_vprintf_l**|**_vprintf_l**|**_vwprintf_l**| +|`_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 \|\*| +|**`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 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 more compatibility information, see [Compatibility](../compatibility.md). ## See also 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 8d26b540659..5b66cf70091 100644 --- a/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md +++ b/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md @@ -36,30 +36,30 @@ Variable argument list. ## 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](../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 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](../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`](../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 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. 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. > [!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](../scanf-width-specification.md). ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vtscanf_s**|**vscanf_s**|**vscanf_s**|**vwscanf_s**| +|`_vtscanf_s`|**`vscanf_s`**|**`vscanf_s`**|**`vwscanf_s`**| For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). @@ -67,10 +67,10 @@ For more information, see [Format specification fields: `scanf` and `wscanf` fun |Routine|Required header| |-------------|---------------------| -|**vscanf_s**|\| -|**wscanf_s**|\ or \| +|**`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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Example diff --git a/docs/c-runtime-library/reference/vscanf-vwscanf.md b/docs/c-runtime-library/reference/vscanf-vwscanf.md index 0b700984ddc..b078291bb51 100644 --- a/docs/c-runtime-library/reference/vscanf-vwscanf.md +++ b/docs/c-runtime-library/reference/vscanf-vwscanf.md @@ -38,24 +38,24 @@ Variable argument list. 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 *`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**. +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`](../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 -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|TCHAR.H routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vtscanf**|**vscanf**|**vscanf**|**vwscanf**| +|`_vtscanf`|**`vscanf`**|**`vscanf`**|**`vwscanf`**| For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). @@ -63,10 +63,10 @@ For more information, see [Format specification fields: `scanf` and `wscanf` fun |Routine|Required header| |-------------|---------------------| -|**vscanf**|\| -|**vwscanf**|\ or \| +|**`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 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 more compatibility information, see [Compatibility](../compatibility.md). ## Example 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 efb613ff437..c5b419013c1 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 @@ -59,7 +59,7 @@ These functions differ from **`_vscprintf`** and **`_vscwprintf`** only in that The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -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`**. +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). @@ -67,7 +67,7 @@ If *`format`* is a null pointer, the invalid parameter handler is invoked, as de ### 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| |---------------------|------------------------------------|--------------------|-----------------------| |**`_vsctprintf_p`**|**`_vscprintf_p`**|**`_vscprintf_p`**|**`_vscwprintf_p`**| |**`_vsctprintf_p_l`**|**`_vscprintf_p_l`**|**`_vscprintf_p_l`**|**`_vscwprintf_p_l`**| 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 41455f59973..c5490a3ca6b 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 @@ -51,11 +51,11 @@ For more information, see [Format specification syntax](../format-specification- ## 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 does not 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](../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 @@ -68,17 +68,17 @@ Each *`argument`* (if any) is converted according to the corresponding format sp ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vsctprintf**|**_vscprintf**|**_vscprintf**|**_vscwprintf**| -|**_vsctprintf_l**|**_vscprintf_l**|**_vscprintf_l**|**_vscwprintf_l**| +|`_vsctprintf`|**`_vscprintf`**|**`_vscprintf`**|**`_vscwprintf`**| +|`_vsctprintf_l`|**`_vscprintf_l`**|**`_vscprintf_l`**|**`_vscwprintf_l`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**_vscprintf**, **_vscprintf_l**|\| -|**_vscwprintf**, **_vscwprintf_l**|\ or \| +|**`_vscprintf`**, **`_vscprintf_l`**|\| +|**`_vscwprintf`**, **`_vscwprintf_l`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.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 5fd7f47cbb4..9ce0d50c34a 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 @@ -103,18 +103,18 @@ For more information, see [Format specifications](../format-specification-syntax * If *`count`* is equal to or exceeds *`sizeOfBuffer`* but the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written (with terminating null) and the number of characters is returned. -* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *`buffer`* to an empty string, set **`errno`** to **`ERANGE`**, and return -1. +* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *`buffer`* to an empty string, set `errno` to `ERANGE`, and return -1. -* If *`buffer`* or *`format`* is a **`NULL`** pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. +* 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`**| +|`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`**| +|*`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`| ## Remarks @@ -131,7 +131,7 @@ The versions of these functions with the **`_l`** suffix are identical except th > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). > [!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). 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 1efbe9cd7d9..f3153f762c5 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 @@ -114,9 +114,9 @@ Both **`_vsnprintf`** and **`_vsnwprintf`** functions return the number of chara 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](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +- 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](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. ## Remarks 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 c02e2914e54..a6ef2ca254e 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 @@ -66,34 +66,34 @@ The locale to use. ## Return value -**_vsprintf_p** and **_vswprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vsprintf_p`** and **`_vswprintf_p`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. ## 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`*. -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). +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](../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, if count is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). ### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|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**| +|`_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 \|\*| +|**`_vsprintf_p`**, **`_vsprintf_p_l`**|\ and \|\*| +|**`_vswprintf_p`**, **`_vswprintf_p_l`**|\ or \, and \|\*| \* Required for UNIX V compatibility. 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 6bdbd71aa73..5ff26788872 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 @@ -75,7 +75,7 @@ The locale to use. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -96,7 +96,7 @@ In C++, using these functions is simplified by template overloads. The overloads ### 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| |---------------------|------------------------------------|--------------------|-----------------------| |**`_vstprintf_s`**|**`vsprintf_s`**|**`vsprintf_s`**|**`vswprintf_s`**| |**`_vstprintf_s_l`**|**`_vsprintf_s_l`**|**`_vsprintf_s_l`**|**`_vswprintf_s_l`**| 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 080d676873e..fd1f05555f4 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 @@ -93,7 +93,7 @@ The locale to use. ## 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`**. +**`vsprintf`** and **`vswprintf`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a `NULL` pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). @@ -107,13 +107,13 @@ The versions of these functions with the **`_l`** suffix are identical except th > 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](../secure-template-overloads.md). ### 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| |---------------------|------------------------------------|--------------------|-----------------------| |**`_vstprintf`**|**`vsprintf`**|**`vsprintf`**|**`vswprintf`**| |**`_vstprintf_l`**|**`_vsprintf_l`**|**`_vsprintf_l`**|**`_vswprintf_l`**| 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 2a2422990da..16950d9ea5d 100644 --- a/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md +++ b/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md @@ -41,39 +41,39 @@ Variable argument list. ## 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 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. -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**. +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`](../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 an additional 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. 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`** 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. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vstscanf_s**|**vsscanf_s**|**vsscanf_s**|**vswscanf_s**| +|`_vstscanf_s`|**`vsscanf_s`**|**`vsscanf_s`**|**`vswscanf_s`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**vsscanf_s**|\| -|**vswscanf_s**|\ or \| +|**`vsscanf_s`**|\| +|**`vswscanf_s`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/vsscanf-vswscanf.md b/docs/c-runtime-library/reference/vsscanf-vswscanf.md index 1f27c30699b..1cac9697952 100644 --- a/docs/c-runtime-library/reference/vsscanf-vswscanf.md +++ b/docs/c-runtime-library/reference/vsscanf-vswscanf.md @@ -42,33 +42,33 @@ Variable argument list. ## 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 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. -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**. +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`](../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`** does not handle multibyte hexadecimal characters. **`vswscanf`** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`vswscanf`** and **`vsscanf`** behave identically. ### 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| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vstscanf**|**vsscanf**|**vsscanf**|**vswscanf**| +|`_vstscanf`|**`vsscanf`**|**`vsscanf`**|**`vswscanf`**| ## Requirements |Routine|Required header| |-------------|---------------------| -|**vsscanf**|\| -|**vswscanf**|\ or \| +|**`vsscanf`**|\| +|**`vswscanf`**|\ or \| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/wcrtomb-s.md b/docs/c-runtime-library/reference/wcrtomb-s.md index a90432c5d09..0fe5ae3e385 100644 --- a/docs/c-runtime-library/reference/wcrtomb-s.md +++ b/docs/c-runtime-library/reference/wcrtomb-s.md @@ -48,19 +48,19 @@ The size of the *`mbchar`* variable in bytes. A wide character to convert. *`mbstate`*\ -A pointer to an **mbstate_t** object. +A pointer to an `mbstate_t` object. ## 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`* does not have a corresponding multibyte character, the value of *`pReturnValue`* will be -1 and the function will return 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](../secure-template-overloads.md). @@ -68,7 +68,7 @@ By default, this function's global state is scoped to the application. To change ## 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 @@ -118,7 +118,7 @@ The corresponding wide character "Q" was converted to a the "Q" multibyte charac |Routine|Required header| |-------------|---------------------| -|**wcrtomb_s**|\| +|**`wcrtomb_s`**|\| ## See also diff --git a/docs/c-runtime-library/reference/wcrtomb.md b/docs/c-runtime-library/reference/wcrtomb.md index dde5496257e..76951ea2d85 100644 --- a/docs/c-runtime-library/reference/wcrtomb.md +++ b/docs/c-runtime-library/reference/wcrtomb.md @@ -39,7 +39,7 @@ The resulting multibyte converted character. A wide character to convert. *`mbstate`*\ -A pointer to an **mbstate_t** object. +A pointer to an `mbstate_t` object. ## Return value @@ -47,11 +47,11 @@ Returns the number of bytes required to represent the converted multibyte charac ## 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`* does not 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](../secure-template-overloads.md). @@ -59,7 +59,7 @@ By default, this function's global state is scoped to the application. To change ## 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 @@ -108,7 +108,7 @@ The corresponding wide character "Q" was converted to the "Q" multibyte characte |Routine|Required header| |-------------|---------------------| -|**wcrtomb**|\| +|**`wcrtomb`**|\| ## See also diff --git a/docs/c-runtime-library/reference/wcsrtombs-s.md b/docs/c-runtime-library/reference/wcsrtombs-s.md index 0a7e166db26..0b132a6f0cf 100644 --- a/docs/c-runtime-library/reference/wcsrtombs-s.md +++ b/docs/c-runtime-library/reference/wcsrtombs-s.md @@ -53,23 +53,23 @@ Points to the wide character string to be converted. 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. +A pointer to an `mbstate_t` conversion state object. ## Return value Zero if successful, an error code on failure. -|Error condition|Return value and **errno**| +|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**| +|*`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](../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 @@ -79,18 +79,18 @@ The **wcsrtombs_s** function converts a string of wide characters pointed to by The destination string is always null-terminated (even in the case of an error). -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 *`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`* 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** 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 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 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. -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](../secure-template-overloads.md). @@ -98,7 +98,7 @@ By default, this function's global state is scoped to the application. To change ## 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 @@ -151,7 +151,7 @@ The string was successfully converted. |Routine|Required header| |-------------|---------------------| -|**wcsrtombs_s**|\| +|**`wcsrtombs_s`**|\| ## See also diff --git a/docs/c-runtime-library/reference/wcsrtombs.md b/docs/c-runtime-library/reference/wcsrtombs.md index 6a3899223a9..197d41e7894 100644 --- a/docs/c-runtime-library/reference/wcsrtombs.md +++ b/docs/c-runtime-library/reference/wcsrtombs.md @@ -44,7 +44,7 @@ Indirectly points to the location of the wide character string to be converted. The number of character to be converted. *`mbstate`*\ -A pointer to an **mbstate_t** conversion state object. +A pointer to an `mbstate_t` conversion state object. ## Return value @@ -52,13 +52,13 @@ Returns the number of bytes successfully converted, not including the null termi ## 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`* does not 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](../secure-template-overloads.md). @@ -66,7 +66,7 @@ By default, this function's global state is scoped to the application. To change ## 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`* is not null. ## Example @@ -118,7 +118,7 @@ The string was successfuly converted. |Routine|Required header| |-------------|---------------------| -|**wcsrtombs**|\| +|**`wcsrtombs`**|\| ## See also 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 c0dcd6d3747..7b2a72914ac 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 @@ -75,13 +75,13 @@ The locale to use. Zero if successful, an error code on failure. -|Error condition|Return value and **`errno`**| +|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`**| +|*`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](../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 @@ -95,11 +95,11 @@ The **`wcstombs_s`** function converts a string of wide characters pointed to by The destination string is always null-terminated (even in the case of an error). -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 *`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`* 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`** 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 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 the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcstombs_s`** is undefined. diff --git a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md index ae3b2663659..71bcbe0a454 100644 --- a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md +++ b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md @@ -58,7 +58,7 @@ The locale to use. ## 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 @@ -66,9 +66,9 @@ The **`wcstombs`** function converts the wide-character string pointed to by *`w 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](../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](../locale.md). diff --git a/docs/c-runtime-library/reference/wctob.md b/docs/c-runtime-library/reference/wctob.md index 640397988a6..eb2cceb4cbc 100644 --- a/docs/c-runtime-library/reference/wctob.md +++ b/docs/c-runtime-library/reference/wctob.md @@ -29,13 +29,13 @@ Value to translate. ## 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 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. ## 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 return **`int`** value, if the multibyte character is exactly one 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 behavior, see [Global state in the CRT](../global-state.md). @@ -43,13 +43,13 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**wctob**|\| +|**`wctob`**|\| 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 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 8e1f399aed7..d3ec6518d0d 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 @@ -57,19 +57,19 @@ Error Conditions |*`mbchar`*|*`sizeInBytes`*|Return value|*`pRetValue`*| |--------------|-------------------|------------------|-----------------| -|**NULL**|>0|**EINVAL**|not modified| -|any|>**INT_MAX**|**EINVAL**|not modified| -|any|too small|**EINVAL**|not modified| +|`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](../parameter-validation.md). If execution is allowed to continue, `wctomb` returns `EINVAL` and sets `errno` to `EINVAL`. ## 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 is not 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -77,14 +77,14 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**wctomb_s**|\| -|**_wctomb_s_l**|\| +|**`wctomb_s`**|\| +|**`_wctomb_s_l`**|\| 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 diff --git a/docs/c-runtime-library/reference/wctomb-wctomb-l.md b/docs/c-runtime-library/reference/wctomb-wctomb-l.md index ab0601083e5..9f7313e1439 100644 --- a/docs/c-runtime-library/reference/wctomb-wctomb-l.md +++ b/docs/c-runtime-library/reference/wctomb-wctomb-l.md @@ -38,13 +38,13 @@ A wide character. ## 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 is not 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](../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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -52,7 +52,7 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**wctomb**|\| +|**`wctomb`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/wctrans.md b/docs/c-runtime-library/reference/wctrans.md index 8c166b32a2d..25ac0a3ea1c 100644 --- a/docs/c-runtime-library/reference/wctrans.md +++ b/docs/c-runtime-library/reference/wctrans.md @@ -29,7 +29,7 @@ A string that specifies one of the valid transformations. ## 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 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). ## Remarks @@ -46,7 +46,7 @@ The following pairs of calls have the same behavior in all locales, but it is po |Routine|Required Header| |-------------|---------------------| -|**wctrans**|\| +|**`wctrans`**|\| For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/wctype.md b/docs/c-runtime-library/reference/wctype.md index d3fdbad607a..83694b26ebb 100644 --- a/docs/c-runtime-library/reference/wctype.md +++ b/docs/c-runtime-library/reference/wctype.md @@ -28,7 +28,7 @@ Property string. ## 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 diff --git a/docs/c-runtime-library/reference/write.md b/docs/c-runtime-library/reference/write.md index f057aa4829a..b6b9209f050 100644 --- a/docs/c-runtime-library/reference/write.md +++ b/docs/c-runtime-library/reference/write.md @@ -36,13 +36,13 @@ Number of bytes. ## 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](../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 to be written to a file in Unicode mode. 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 diff --git a/docs/c-runtime-library/routine-mappings.md b/docs/c-runtime-library/routine-mappings.md index 46c9164b328..8578e846eac 100644 --- a/docs/c-runtime-library/routine-mappings.md +++ b/docs/c-runtime-library/routine-mappings.md @@ -15,7 +15,7 @@ For related information, see [Generic-text mappings in tchar.h](../text/generic- ### Generic-text routine mappings -|Generic-text routine name|SBCS (_UNICODE & MBCS not defined)|_MBCS defined|_UNICODE defined| +|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`| diff --git a/docs/c-runtime-library/rtdynamiccast.md b/docs/c-runtime-library/rtdynamiccast.md index fd63bc2caf5..52789cabef4 100644 --- a/docs/c-runtime-library/rtdynamiccast.md +++ b/docs/c-runtime-library/rtdynamiccast.md @@ -45,7 +45,7 @@ Intended result of cast. ## Return value -Pointer to the appropriate subobject, if successful; otherwise, **NULL**. +Pointer to the appropriate subobject, if successful; otherwise, `NULL`. ## Exceptions 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 4a653e23388..6e97523932b 100644 --- a/docs/c-runtime-library/sbcs-and-mbcs-data-types.md +++ b/docs/c-runtime-library/sbcs-and-mbcs-data-types.md @@ -16,13 +16,13 @@ Any Microsoft MBCS run-time library routine that handles only a single multibyte 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 behavior is the default. -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 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 method is the slowest, 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 diff --git a/docs/c-runtime-library/searching-and-sorting.md b/docs/c-runtime-library/searching-and-sorting.md index 207654cbb8b..405d72ec8ce 100644 --- a/docs/c-runtime-library/searching-and-sorting.md +++ b/docs/c-runtime-library/searching-and-sorting.md @@ -14,13 +14,13 @@ Use the following functions for searching and sorting. |Function|Search or Sort| |--------------|--------------------| |[`bsearch`](./reference/bsearch.md)|Binary search| -|[`bsearch_s`](./reference/bsearch-s.md)|A more secure version of **bsearch**| +|[`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**| +|[`_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**| +|[`_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**| +|[`qsort_s`](./reference/qsort-s.md)|A more secure version of `qsort`| ## See also 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 403253aeeb5..1953ede658f 100644 --- a/docs/c-runtime-library/security-features-in-the-crt.md +++ b/docs/c-runtime-library/security-features-in-the-crt.md @@ -42,7 +42,7 @@ Some of the security features include: 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. diff --git a/docs/c-runtime-library/setvbuf-constants.md b/docs/c-runtime-library/setvbuf-constants.md index 20d803b6929..4f440c1143e 100644 --- a/docs/c-runtime-library/setvbuf-constants.md +++ b/docs/c-runtime-library/setvbuf-constants.md @@ -22,7 +22,7 @@ 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.| +|`_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`.| diff --git a/docs/c-runtime-library/spawn-wspawn-functions.md b/docs/c-runtime-library/spawn-wspawn-functions.md index fcddc7f17b9..9920bba06be 100644 --- a/docs/c-runtime-library/spawn-wspawn-functions.md +++ b/docs/c-runtime-library/spawn-wspawn-functions.md @@ -85,13 +85,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. (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. +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. 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 b2de049ae2d..29a7d22430b 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 @@ -16,7 +16,7 @@ ms.assetid: fd462004-7563-4766-8443-30b0a86174b6 ## Remarks -These constants are used to indicate file type in the **st_mode** field of the [`_stat` structure](./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: diff --git a/docs/c-runtime-library/stream-i-o.md b/docs/c-runtime-library/stream-i-o.md index 3ddd57c1264..9179e21a4ce 100644 --- a/docs/c-runtime-library/stream-i-o.md +++ b/docs/c-runtime-library/stream-i-o.md @@ -32,7 +32,7 @@ These functions process data in different sizes and formats, from single charact |[`_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| +|[`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| 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 09ba407c28f..7a3cde2713a 100644 --- a/docs/c-runtime-library/text-and-binary-mode-file-i-o.md +++ b/docs/c-runtime-library/text-and-binary-mode-file-i-o.md @@ -11,11 +11,11 @@ File I/O operations take place in one of two translation modes, *text* or *binar - Retain the current default setting and specify the alternative mode only when you open selected files. -- Use the function [`_set_fmode`](./reference/set-fmode.md) to change the default mode for newly opened files. Use [`_get_fmode`](./reference/get-fmode.md) to find the current default mode. The initial default setting is text mode (**_O_TEXT**). +- Use the function [`_set_fmode`](./reference/set-fmode.md) to change the default mode for newly opened files. Use [`_get_fmode`](./reference/get-fmode.md) to find the current default mode. The initial default setting is text mode (`_O_TEXT`). -- Change the default translation mode directly by setting the global variable [`_fmode`](./fmode.md) in your program. The function **_set_fmode** sets the value of this variable, but it can also be set directly. +- 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`](./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. +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 diff --git a/docs/c-runtime-library/time-management.md b/docs/c-runtime-library/time-management.md index e5def17e58c..6b45a14c158 100644 --- a/docs/c-runtime-library/time-management.md +++ b/docs/c-runtime-library/time-management.md @@ -35,7 +35,7 @@ The **`_ftime`** and **`localtime`** routines use the **`TZ`** environment varia > In all versions of Microsoft C/C++ except Microsoft C/C++ version 7.0, and in all versions of Visual C++, the time function returns the current time as the number of seconds elapsed since midnight on January 1, 1970. In Microsoft C/C++ version 7.0, **`time`** returned the current time as the number of seconds elapsed since midnight on December 31, 1899. > [!NOTE] -> In versions of Visual C++ and Microsoft C/C++ before Visual Studio 2005, **`time_t`** was a **`long int`** (32 bits) and hence could not be used for dates past 3:14:07 January 19, 2038, UTC. **`time_t`** is now equivalent to **`__time64_t`** by default, but defining **`_USE_32BIT_TIME_T`** changes **`time_t`** to **`__time32_t`** and forces many time functions to call versions that take the 32-bit **`time_t`**. For more information, see [Standard types](./standard-types.md) and comments in the documentation for the individual time functions. +> In versions of Visual C++ and Microsoft C/C++ before Visual Studio 2005, **`time_t`** was a **`long int`** (32 bits) and hence could not be used for dates past 3:14:07 January 19, 2038, UTC. **`time_t`** is now equivalent to **`__time64_t`** by default, but defining `_USE_32BIT_TIME_T` changes **`time_t`** to **`__time32_t`** and forces many time functions to call versions that take the 32-bit **`time_t`**. For more information, see [Standard types](./standard-types.md) and comments in the documentation for the individual time functions. ## See also diff --git a/docs/c-runtime-library/to-functions.md b/docs/c-runtime-library/to-functions.md index 6c4b7ff3286..585f230a6e7 100644 --- a/docs/c-runtime-library/to-functions.md +++ b/docs/c-runtime-library/to-functions.md @@ -31,7 +31,7 @@ The **`to`** functions and macro conversions are as follows. |`_toupper`|`_toupper`|Converts `c` to uppercase| |`towupper`|None|Converts c to corresponding wide-character uppercase letter| -To use the function versions of the **to** routines that are also defined as macros, either remove the macro definitions with `#undef` directives or don't include CTYPE.H. If you use the /Za compiler option, the compiler uses the function version of `toupper` or `tolower`. Declarations of the `toupper` and `tolower` functions are in STDLIB.H. +To use the function versions of the **`to`** routines that are also defined as macros, either remove the macro definitions with `#undef` directives or don't include CTYPE.H. If you use the /Za compiler option, the compiler uses the function version of `toupper` or `tolower`. Declarations of the `toupper` and `tolower` functions are in STDLIB.H. The `__toascii` routine sets all but the low-order 7 bits of `c` to 0, so that the converted value represents a character in the ASCII character set. If `c` already represents an ASCII character, `c` is unchanged. 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 3b46f04bdd5..c6c1034d8e8 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 @@ -8,9 +8,9 @@ ms.assetid: 68be0c3e-a9e6-4fd5-b34a-1b5207f0e7d6 --- # 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. 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 a14ea22fcff..2a18a516783 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 @@ -10,11 +10,11 @@ ms.assetid: 48f471e7-9d2b-4a39-b841-16a0e15c0a18 **Microsoft Specific** -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: +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 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. + 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. @@ -53,7 +53,7 @@ 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](./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** diff --git a/docs/c-runtime-library/vprintf-functions.md b/docs/c-runtime-library/vprintf-functions.md index 21e1495cf0f..5fec57e7c73 100644 --- a/docs/c-runtime-library/vprintf-functions.md +++ b/docs/c-runtime-library/vprintf-functions.md @@ -61,18 +61,18 @@ These functions format data for output to destinations as follows. 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 **_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 **`_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 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). +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 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 e286321d8e7..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,7 +12,7 @@ UWP apps don't support the following CRT features: - Most CRT functions that are related to unsupported functionality. - For example, a UWP app can't 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 isn't supported in a UWP app, that fact is noted in its reference article.