Definito nell'intestazione
(1)
char*strncpy(char*dest,constchar*src,size_t count );
(fino a C99)
char*strncpy(char*restrict dest,constchar*restrict src,size_t count );
(dal C99)
errno_tstrncpy_s(char*restrict dest,rsize_t destsz,constchar*restrict src,rsize_t count);
(2) (dal C11)

1) Copie al massimo count caratteri dell'array di caratteri puntato da src (compreso il carattere nullo finale, ma non i caratteri che seguono il carattere nullo) nell'array di caratteri puntato da dest.
Se count viene raggiunto prima dell'intero array src è stato copiato, la matrice di caratteri risultante non è a terminazione nulla.
Se, dopo aver copiato il carattere nullo terminante da src, count non viene raggiunto, vengono scritti altri caratteri nulli in dest finché il totale di count fino a quando non viene scritto un totale di countcaratteri.
Il comportamento è indefinito se gli array di caratteri si sovrappongono, se uno dei due array di caratteri dest o src non è un puntatore a un array di caratteri (anche se dest o src è un puntatore nullo), se la dimensione dell'array puntato da dest è inferiore a count o se la dimensione dell'array puntato da src è inferiore a counte non contiene un carattere nullo.2) Uguale a (1) tranne per il fatto che la funzione non continua a scrivere zeri nell'array di destinazione per riempire fino a count ma si ferma dopo aver scritto il carattere nullo di terminazione (se non c'era alcun nullo nella sorgente, ne scrive uno in corrispondenza di dest[count] e poi si ferma). Inoltre, i seguenti errori vengono rilevati in fase di esecuzione e chiamano la funzione di gestione dei vincoli attualmente installata:

  • src o dest è un puntatore nullo
  • destsz o count è zero o maggiore di RSIZE_MAX
  • count è maggiore o uguale a destsz, ma destsz è minore o uguale a strnlen_s(src, count), in altre parole, si verificherebbe il troncamento
  • si verificherebbe una sovrapposizione tra le stringhe di origine e quelle di destinazione

Il comportamento è indefinito se la dimensione dell'array di caratteri puntato da dest strnlen_s(src, destsz) <= destsz; in altre parole, un valore errato di destsz non rivela l'imminente overflow del buffer. Il comportamento è indefinito se la dimensione dell'array di caratteri puntato da src strnlen_s(src, count) destsz; in altre parole, un valore errato di count non rivela l'imminente overflow del buffer. Come per tutte le funzioni con controllo dei limiti, strncpy_s è garantito solo se __STDC_LIB_EXT1__ è definito dall'implementazione e se l'utente definisce __STDC_WANT_LIB_EXT1__ alla costante intera 1 prima di includere string.h.

Parametri

destinazione - puntatore all'array di caratteri in cui copiare
src - puntatore all'array di caratteri da cui copiare
conteggio - numero massimo di caratteri da copiare
destsz - dimensione del buffer di destinazione

Valore di ritorno

1) restituisce una copia di dest2) restituisce zero in caso di successo, restituisce non-zero in caso di errore. Inoltre, in caso di errore, scrive zero in dest[0] (a meno che dest sia un puntatore nullo o destsz sia zero o maggiore di RSIZE_MAX) e può bloccare il resto dell'array di destinazione con valori non specificati.

Note

Come corretto dal DR 468 post-C11, strncpy_s, a differenza di strcpy_sè autorizzato a distruggere il resto dell'array di destinazione solo se si verifica un errore.

A differenza di strncpy, strncpy_s non riempie l'array di destinazione con zeri, il che è una fonte comune di errori quando si converte il codice esistente nella versione con controllo dei limiti.

Anche se il troncamento per adattarsi al buffer di destinazione è un rischio per la sicurezza e quindi una violazione dei vincoli di runtime per strncpy_sè possibile ottenere il comportamento di troncamento specificando count uguale alla dimensione dell'array di destinazione meno uno: verrà copiato il primo elemento counte aggiungerà il terminatore nullo come sempre: strncpy_s(dst, sizeof dst, src, (sizeof dst)-1);

Esempio

#define__STDC_WANT_LIB_EXT1__1#include#include#includeintmain(void){char src[]="hi";char dest[6]="abcdef";// no null terminatorstrncpy(dest, src,5);// writes five characters 'h', 'i', '', '', '' to destprintf("strncpy(dest, src, 5) to a 6-byte dest gives : ");for(size_t n =0; n <sizeof dest;++n){char c = dest[n];
        c ?printf("'%c' ", c):printf("'\0' ");}printf("nstrncpy(dest2, src, 2) to a 2-byte dst gives : ");char dest2[2];strncpy(dest2, src,2);// truncation: writes two characters 'h', 'i', to dest2for(size_t n =0; n <sizeof dest2;++n){char c = dest2[n];
        c ?printf("'%c' ", c):printf("'\0' ");}printf("n");#ifdef__STDC_LIB_EXT1__set_constraint_handler_s(ignore_handler_s);char dst1[6], src1[100]="hello";int r1 =strncpy_s(dst1,6, src1,100);// writes 0 to r1, 6 characters to dst1printf("dst1 = "%s", r1 = %dn", dst1,r1);// 'h','e','l','l','o','' to dst1char dst2[5], src2[7]={'g','o','o','d','b','y','e'};int r2 =strncpy_s(dst2,5, src2,7);// copy overflows the destination arrayprintf("dst2 = "%s", r2 = %dn", dst2,r2);// writes nonzero to r2,'' to dst2[0]char dst3[5];int r3 =strncpy_s(dst3,5, src2,4);// writes 0 to r3, 5 characters to dst3printf("dst3 = "%s", r3 = %dn", dst3,r3);// 'g', 'o', 'o', 'd', '' to dst3 #endif}

Possibile uscita:

strncpy(dest, src,5) to a 6-byte dst gives :'h''i''''''''f'strncpy(dest2, src,2) to a 2-byte dst gives :'h''i'
dst1 ="hello", r1 =0
dst2 ="", r2 =22
dst3 ="good", r3 =0

Riferimenti

  • Norma C11 (ISO/IEC 9899:2011):
    • 7.24.2.4 La funzione strncpy (p: 363-364)
    • K.3.7.1.4 La funzione strncpy_s (p: 616-617)
  • Standard C99 (ISO/IEC 9899:1999):
    • 7.21.2.4 La funzione strncpy (p: 326-327)
  • Standard C89/C90 (ISO/IEC 9899:1990):
    • 4.11.2.4 La funzione strncpy

Vedere anche

strcpystrcpy_s(C11) copia una stringa in un'altra
(funzione)
memcpymemcpy_s(C11) copia un buffer in un altro
(funzione)
strndup(memoria dinamica TR) alloca una copia di una stringa fino alla dimensione specificata
(funzione)