strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Artykuł
06/09/2015

Skopiować jeden ciąg znaków na inny.Bardziej bezpieczne wersje tych funkcji są dostępne w strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

Ważne
_mbsncpy i _mbsncpy_l nie można używać w aplikacjach korzystających ze Środowisko wykonawcze systemu Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /ZW.

char *strncpy(
   char *strDest,
   const char *strSource,
   size_t count 
);
char *_strncpy_l(
   char *strDest,
   const char *strSource,
   size_t count,
   locale_t locale 
);
wchar_t *wcsncpy(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
wchar_t *_wcsncpy_l(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
);
unsigned char *_mbsncpy(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count 
);
unsigned char *_mbsncpy_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncpy(
   char (&strDest)[size],
   const char *strSource,
   size_t count 
); // C++ only
template <size_t size>
char *_strncpy_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
wchar_t *wcsncpy(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
wchar_t *_wcsncpy_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parametry

strDest
Ciąg docelowy.
strSource
Ciąg źródłowy.
count
Liczba znaków, które mają być kopiowane.
locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zwraca strDest.Nie zwraca żadnej wartości zarezerwowanej, aby wskazać błąd.

Uwagi

strncpy Funkcja kopiuje wstępnego count znaków z strSource do strDest i zwraca strDest.Jeśli count jest mniejsza lub równa długości strSource, znak null nie są automatycznie dołączane do skopiowanego ciąg.Jeśli count jest większa niż długość strSource, ciąg docelowy jest wypełniane znakami null do długości count.Zachowanie strncpy jest niezdefiniowane, jeżeli ciągi źródłowe i docelowe nakładają się.

Uwaga dotycząca zabezpieczeń
strncpynie sprawdza wystarczająco dużo miejsca w strDest; w ten sposób potencjalne przyczyny przekroczenia buforu.count Argument ogranicza liczbę znaków kopiowane; nie jest limit rozmiaru strDest.Zobacz przykład poniżej.Aby uzyskać więcej informacji, zobacz unikanie przekroczenia buforu.

Jeśli strDest lub strSource jest NULL wskaźnik, lub jeśli count jest mniejsza niż lub równa zero, obsługi nieprawidłowy parametr jest wywoływany, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje zwracają wartość -1 i ustawiają errno na EINVAL

wcsncpy i _mbsncpy są wersjami znaków dwubajtowych i znaków wielobajtowych strncpy.Argumenty i wartości zwracanej przez wcsncpy i _mbsncpy odpowiednio zmienić.W innych przypadkach te sześć funkcji zachowuje się identycznie.

Wersje tych funkcji, które mają przyrostek _l są identyczne, z tą różnicą, że używają ustawień regionalnych, które są przekazywane do zachowań zależnych od ustawień regionalnych, zamiast bieżących ustawień regionalnych.Aby uzyskać więcej informacji, zobacz Regionalne.

W języku programowania C++ funkcje te mają przeciążenia szablonu, które wywołują nowsze, bezpieczne odpowiedniki tych funkcji.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_tcsncpy	strncpy	_mbsnbcpy	wcsncpy
_tcsncpy_l	_strncpy_l	_mbsnbcpy_l	_wcsncpy_l

[!UWAGA]

_strncpy_li _wcsncpy_l mają ma zależności ustawień regionalnych; są one świadczone tylko dla _tcsncpy_l i nie są przeznaczone do bezpośredniego wywoływania.

Wymagania

Procedura	Wymagany nagłówek
strncpy	<Ciąg>
wcsncpy	<ciągo.h> lub <wchar.h>
_mbsncpy, _mbsncpy_l	<mbCiąg.h>

Dla platforma dodatkowe informacje o zgodności, zobacz zgodności.

Przykład

Poniższy przykład demonstruje użycie strncpy i jak może być nadużywane powodować błędy programu i kwestie bezpieczeństwa.Kompilator generuje ostrzeżenie dla każdego wywołania strncpy podobne docrt_strncpy_x86.c(15) : warning C4996: 'strncpy': This function or variable may be unsafe. Consider using strncpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.

// crt_strncpy_x86.c
// Use this command in an x86 developer command prompt to compile: 
// cl /TC /W3 crt_strncpy_x86.c

#include <stdio.h>
#include <string.h>

int main() {
   char t[20];
   char s[20];
   char *p = 0, *q = 0;

   strcpy_s(s, sizeof(s), "AA BB CC");
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy(s, "aa", 2);     // "aa BB CC"         C4996
   strncpy(s + 3, "bb", 2); // "aa bb CC"         C4996
   strncpy(s, "ZZ", 3);     // "ZZ",              C4996
                            // count greater than strSource, null added
   printf("%s\n", s);

   strcpy_s(s, sizeof(s), "AA BB CC");
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf("%s\n", s);

   // some problems with strncpy
   strcpy_s(s, sizeof(s), "test");
   strncpy(t, "this is a very long string", 20 ); // C4996
   // Danger: at this point, t has no terminating null,
   // so the printf continues until it runs into one.
   // In this case, it will print "this is a very long test"
   printf("%s\n", t);

   strcpy_s(t, sizeof(t), "dogs like cats");
   printf("%s\n", t);

   strncpy(t + 10, "to chase cars.", 14); // C4996
   printf("%s\n", t);

   // strncpy has caused a buffer overrun and corrupted string s
   printf("Buffer overrun: s = '%s' (should be 'test')\n", s);
   // Since the stack grows from higher to lower addresses, buffer
   // overruns can corrupt function return addresses on the stack,
   // which can be exploited to run arbitrary code.
}

Dane wyjściowe

Układ automatyczny zmiennych i poziomu ochrony wykrywania i kod błędu mogą się różnić z kompilatora zmienionych ustawień.W tym przykładzie mogą mieć różne wyniki, kiedy budowane w innych środowiskach kompilacji lub za pomocą innych opcji kompilatora.