6.20.18 strncpy Function

Copy the source string into the destination string, up to the specified number of characters.

Include

<string.h>

Prototype

char *strncpy(char *s1, const char *s2, size_t n);

Arguments

s1

destination string to copy to

s2

source string to copy from

n

number of characters to copy

Return Value

Returns a pointer to the destination string.

Remarks

Copies n characters from the source string to the destination string. If the source string is less than n characters, the destination is filled with null characters to total n characters. If n characters were copied and no null character was found, then the destination string will not be null-terminated. If the strings overlap, the behavior is undefined.

For MPLAB XC16 or XC-DSC functions that can copy to/from specialized memory areas, such as strncpy_eds, strncpy_packed, strncpy_p2d16 or strncpy_p2d24, see “Functions for Specialized Copying and Initialization in the library reference manual relevant to your compiler.”

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

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

int main(void)
{
  char buf1[50] = "We're here";
  char buf2[50] = "Where is the time?";
  char buf3[50] = "Why?";
  char buf4[7]  = "Where?";

  printf("buf1 : %s\n", buf1);
  printf("buf2 : %s\n", buf2);
  printf("buf3 : %s\n", buf3);
  printf("buf4 : %s\n", buf4);

  strncpy(buf1, buf2, 6);
  printf("buf1 after strncpy of 6 characters "
         "of buf2: \n\t%s\n", buf1);
  printf("\t( %d characters)\n", strlen(buf1));
  printf("\n");

  strncpy(buf1, buf2, 18);
  printf("buf1 after strncpy of 18 characters "
         "of buf2: \n\t%s\n", buf1);
  printf("\t( %d characters)\n", strlen(buf1));
  printf("\n");

  strncpy(buf1, buf3, 5);
  printf("buf1 after strncpy of 5 characters "
         "of buf3: \n\t%s\n", buf1);
  printf("\t( %d characters)\n", strlen(buf1));
  printf("\n");

  strncpy(buf1, buf4, 9);
  printf("buf1 after strncpy of 9 characters "
         "of buf4: \n\t%s\n", buf1);
  printf("\t( %d characters)\n", strlen(buf1));
}

Example Output

buf1 : We’re here
buf2 : Where is the time?
buf3 : Why?
buf4 : Where?
buf1 after strncpy of 6 characters of buf2:
        Where here
        ( 10 characters)

buf1 after strncpy of 18 characters of buf2:
        Where is the time?
        ( 18 characters)

buf1 after strncpy of 5 characters of buf3:
        Why?
        ( 4 characters)

buf1 after strncpy of 9 characters of buf4:
        Where?
        ( 6 characters)

Example Explanation

Each buffer contains the string shown, followed by null characters for a length of 50. Using strlen will find the length of the string up to, but not including, the first null character.

In the first example, 6 characters of buf2 (“Where “) replace the first 6 characters of buf1 ("We’re ") and the rest of buf1 remains the same ("here" plus null characters).

In the second example, 18 characters replace the first 18 characters of buf1 and the rest remain null characters.

In the third example, 5 characters of buf3 ("Why?" plus a null terminating character) replace the first 5 characters of buf1. buf1 now actually contains ("Why?", 1 null character, " is the time?", 32 null characters). strlen shows 4 characters because it stops when it reaches the first null character.

In the fourth example, since buf4 is only 7 characters, strncpy uses 2 additional null characters to replace the first 9 characters of buf1. The result of buf1 is 6 characters ("Where?") followed by 3 null characters, followed by 9 characters ("the time?"), followed by 32 null characters.