strncat, strncat_s
De fr.cppreference.net
| Défini dans l'en-tête <string.h>
|
||
char* strncat( char* dest, const char* src, size_t count );
|
(1) | (jusqu'à C99) |
char* strncat( char* restrict dest, const char* restrict src, size_t count );
|
(depuis C99) | |
errno_t strncat_s( char* restrict dest, rsize_t destsz,
const char* restrict src, rsize_t count );
|
(2) | (depuis C11) |
1) Ajoute au maximum
count caractères du tableau de caractères pointé par src, en s'arrêtant si le caractère nul est trouvé, à la fin de la chaîne d'octets terminée par zéro pointée par dest. Le caractère src[0] remplace le terminateur nul à la fin de dest. Le caractère nul de terminaison est toujours ajouté à la fin (donc le nombre maximal d'octets que la fonction peut écrire est count + 1). Le comportement est indéfini si le tableau de destination n'a pas assez d'espace pour le contenu de
dest et les premiers count caractères de src, plus le caractère nul de terminaison. Le comportement est indéfini si les objets source et destination se chevauchent. Le comportement est indéfini si dest n'est pas un pointeur vers une chaîne d'octets terminée par zéro ou si src n'est pas un pointeur vers un tableau de caractères.2) Identique à (1), sauf que cette fonction peut écraser le reste du tableau de destination (à partir du dernier octet écrit jusqu'à
destsz) et que les erreurs suivantes sont détectées au moment de l'exécution et appellent la fonction gestionnaire de contrainte actuellement installée :
srcoudestest un pointeur nuldestszoucountest zéro ou supérieur à RSIZE_MAX- il n'y a pas de caractère nul dans les premiers
destszoctets dedest - une troncature se produirait :
countou la longueur desrc, selon la plus petite, dépasse l'espace disponible entre le terminateur nul dedestetdestsz. - un chevauchement se produirait entre la chaîne source et la chaîne de destination
Le comportement est indéfini si la taille du tableau de caractères pointé par
dest < strnlen(dest, destsz) + strnlen(src,count) + 1 < destsz ; en d'autres termes, une valeur erronée de destsz n'expose pas le dépassement de tampon imminent. Le comportement est indéfini si la taille du tableau de caractères pointé par src < strnlen(src,count) < destsz ; en d'autres termes, une valeur erronée de count n'expose pas le dépassement de tampon imminent. Comme pour toutes les fonctions vérifiées,
strncat_s n'est garanti disponible que si __STDC_LIB_EXT1__ est défini par l'implémentation et si l'utilisateur définit __STDC_WANT_LIB_EXT1__ comme la constante entière 1 avant d'inclure <string.h>.Paramètres
| dest | - | pointeur vers la chaîne d'octets terminée par zéro à laquelle ajouter |
| src | - | pointeur vers le tableau de caractères à copier |
| count | - | nombre maximal de caractères à copier |
| destsz | - | la taille du tampon de destination |
Valeur de retour
1) renvoie une copie de
dest2) renvoie zéro en cas de succès, renvoie une valeur non nulle en cas d'erreur. De plus, en cas d'erreur, écrit zéro dans
dest[0] (sauf si dest est un pointeur nul ou si destsz est zéro ou supérieur à RSIZE_MAX).Notes
Parce que strncat doit chercher la fin de dest à chaque appel, il est inefficace de concaténer plusieurs chaînes en une seule en utilisant strncat.
Bien que la troncature pour s'adapter au tampon de destination soit un risque de sécurité et donc une violation de contrainte d'exécution pour strncat_s, il est possible d'obtenir un comportement de troncature en spécifiant count égal à la taille du tableau de destination moins un : il copiera les premiers count octets et ajoutera le terminateur nul comme toujours : strncat_s(dst, sizeof dst, src, (sizeof dst) - strnlen_s(dst, sizeof dst) - 1);
Exemple
Exécuter ce code
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
int main(void)
{
char str[50] = "Hello ";
char str2[50] = "World!";
strcat(str, str2);
strncat(str, " Goodbye World!", 3);
puts(str);
#ifdef __STDC_LIB_EXT1__
set_constraint_handler_s(ignore_handler_s);
char s1[100] = "good";
char s5[1000] = "bye";
int r1 = strncat_s(s1, 100, s5, 1000); // r1 is 0, s1 holds "goodbye\0"
printf("s1 = %s, r1 = %d\n", s1, r1);
char s2[6] = "hello";
int r2 = strncat_s(s2, 6, "", 1); // r2 is 0, s2 holds "hello\0"
printf("s2 = %s, r2 = %d\n", s2, r2);
char s3[6] = "hello";
int r3 = strncat_s(s3, 6, "X", 2); // r3 is non-zero, s3 holds "\0"
printf("s3 = %s, r3 = %d\n", s3, r3);
// the strncat_s truncation idiom:
char s4[7] = "abc";
int r4 = strncat_s(s4, 7, "defghijklmn", 3); // r4 is 0, s4 holds "abcdef\0"
printf("s4 = %s, r4 = %d\n", s4, r4);
#endif
}
Résultat possible :
Hello World! Go
s1 = goodbye, r1 = 0
s2 = hello, r2 = 0
s3 = , r3 = 22
s4 = abcdef, r4 = 0
Références
- Norme C23 (ISO/IEC 9899:2024) :
- 7.26.3.2 La fonction strncat (p: 379)
- K.3.7.2.2 La fonction strncat_s (p: à déterminer)
- Norme C17 (ISO/IEC 9899:2018) :
- 7.24.3.2 La fonction strncat (p: 265-266)
- K.3.7.2.2 La fonction strncat_s (p: 449-450)
- Norme C11 (ISO/IEC 9899:2011) :
- 7.24.3.2 La fonction strncat (p: 364-365)
- K.3.7.2.2 La fonction strncat_s (p: 618-620)
- Norme C99 (ISO/IEC 9899:1999) :
- 7.21.3.2 La fonction strncat (p: 327-328)
- Norme C89/C90 (ISO/IEC 9899:1990) :
- 4.11.3.2 La fonction strncat
Voir aussi
(C11) |
concatène deux chaînes (fonction) |
(C11) |
copie une chaîne vers une autre (fonction) |
(C23) |
copie un tampon vers un autre, en s'arrêtant après le délimiteur spécifié (fonction) |
Documentation C++ pour strncat
| |