RtlStringCchCopyNA 函数 (ntstrsafe.h)

RtlStringCchCopyNWRtlStringCchCopyNA 函数将字符计数字符串复制到缓冲区,同时限制复制的字符串的大小。

语法

NTSTRSAFEDDI RtlStringCchCopyNA(
  [out] NTSTRSAFE_PSTR pszDest,
  [in]  size_t         cchDest,
  [in]  STRSAFE_PCNZCH pszSrc,
        size_t         cchToCopy
);

参数

[out] pszDest

指向接收复制字符串的调用方提供的缓冲区的指针。 pszSrc 的字符串(最多为 cchSrc 字符)复制到 pszDest 处的缓冲区,并使用 null 字符终止。

[in] cchDest

目标缓冲区的大小(以字符为单位)。 允许的最大字符数是NTSTRSAFE_MAX_CCH。

[in] pszSrc

指向调用方提供的 null 终止字符串的指针。

cchToCopy

要从 pszSrc 复制到 pszDest 提供的缓冲区的最大字符数。

返回值

该函数返回下表中列出的 NTSTATUS 值之一。 有关如何测试 NTSTATUS 值的信息,请参阅 使用 NTSTATUS 值

返回代码 说明
STATUS_SUCCESS
成功 状态表示源数据存在,字符串被复制而不截断,生成的目标缓冲区以 null 结尾。
STATUS_BUFFER_OVERFLOW
警告 状态表示由于目标缓冲区空间不足,复制操作未完成。 目标缓冲区包含已复制字符串的截断版本。
STATUS_INVALID_PARAMETER
此错误状态表示函数收到无效的输入参数。 有关详细信息,请参阅以下段落。

函数在以下情况下返回STATUS_INVALID_PARAMETER值:

  • cchDest 中的值大于最大缓冲区大小。
  • 目标缓冲区已满。
  • 存在 NULL 指针。
  • 目标缓冲区的长度为零,但存在非零长度源字符串。

备注

应使用 RtlStringCchCopyNWRtlStringCchCopyNA 而不是 strncpy

这些函数从源字符串复制给定数量的字符。 RtlStringCchCopyNWRtlStringCchCopyNA 接收目标缓冲区的大小(以字符为单位)以确保函数不会写入缓冲区末尾。

请注意,这些函数在一个方面的行为与 strncpy 不同。 如果 cchSrc 大于 pszSrc 中的字符数,则在复制 cchSrc 字符之前,RtlStringCchCopyNWRtlStringCchCopyNA 不会继续使用 null 字符填充 pszDest

使用 RtlStringCchCopyNW 处理 Unicode 字符串, 使用 RtlStringCchCopyNA 处理 ANSI 字符串。 使用的窗体取决于数据,如下表所示。

字符串数据类型 字符串文本 功能
WCHAR L“string” RtlStringCchCopyNW
char “字符串” RtlStringCchCopyNA
 

如果 pszSrcpszDest 指向重叠字符串,则函数的行为是未定义的。

pszSrcpszDest 都不能为 NULL。 如果需要处理 NULL 字符串指针值,请使用 RtlStringCchCopyNEx

有关安全字符串函数的详细信息,请参阅 使用安全字符串函数

要求

   
最低受支持的客户端 在 Windows XP 中提供 Service Pack 1 (SP1) 及更高版本的 Windows。
目标平台 桌面
Header ntstrsafe.h (包括 Ntstrsafe.h)
Library Ntstrsafe.lib
IRQL PASSIVE_LEVEL

另请参阅

RtlStringCbCopyN

RtlStringCchCopy

RtlStringCchCopyNEx