See also: part 1, part 2, part 3, part 4, part 5 and part 6.

The story so far . . . String copies can be made much safer by using strncpy() instead of strcpy(). strncpy() will take up slightly more code space than strcpy() and may be slower.

Now let’s move on to appending strings with strcat() (“string concatenate”). From the very-useful cplusplus.com website:

• strcat( char *destination, const char *source ) – Concatenate strings. Appends a copy of the source string to the destination string. The terminating null character in destination is overwritten by the first character of source, and a null-character is included at the end of the new string formed by the concatenation of both in destination.

As an example of normal use, perhaps you want to take two string buffers that contain a first and last name, and put them together and make a full name string buffer:

char firstName[40];
char lastName[40];
char fullName[81]; // firstName + space + lastName

// Load first name.
strcpy( firstName, "Zaphod" );

// Load last name.
strcpy( lastName, "Beeblebrox" );

// Create full name by starting with first name...
strcpy( fullName, firstName );

// ...then appending a space...
strcat( fullName, " " );

// ...then appending the last name.
strcat( fullName, lastName );

The fullName buffer looks like this:

// strcpy( fullName, firstName )
+---+---+---+---+---+---+---+---+---+---+---+---+-...
| Z | a | p | h | o | d | 0 |   |   |   |   |   | ...
+---+---+---+---+---+---+---+---+---+---+---+---+-...

// strcat( fullName, " " );
+---+---+---+---+---+---+---+---+---+---+---+---+-...
| Z | a | p | h | o | d |   | 0 |   |   |   |   | ...
+---+---+---+---+---+---+---+---+---+---+---+---+-...

// strcat( fullName, lastName )
+---+---+---+---+---+---+---+---+---+---+---+---+-...
| Z | a | p | h | o | d |   | B | e | e | b | l | ...
+---+---+---+---+---+---+---+---+---+---+---+---+-...

Hopefully you get the idea.

In this simple example, we are controlling the length of the name strings being copied in. We know that fullName can hold 81 bytes, so we know firstName and lastName plus the space in between must be less than 81 bytes long to avoid overflowing the fullName buffer.

In a perfect world, that is fine.  But in a perfect world, we would never need any error checking. Let’s just pretend the world isn’t perfect and do this the safe(r) way.

Just like strcpy() has strncpy(), strcat() also has a safer version. It is called strncat():

• char * strncat ( char * destination, const char * source, size_t num ) – Append characters from string. Appends the first num characters of source to destination, plus a terminating null-character.
  
  If the length of the C string in source is less than num, only the content up to the terminating null-character is copied.

For strncat(), num specifies how many characters of the source to append to the destination buffer. If you know the destination buffer (fullName, in this example) is 81 characters (because it is, in this example), you might think you could just do this:

strncat( fullName, firstName, 81 );

While you can do that, that would be wrong. The num count only controls how many characters are appended — it does not have anything to do with the count of how many characters are already in the destination buffer. For example, say fullName already has a 6 character firstName copied to it:

+---+---+---+---+---+---+---+---+--...--+---+---+---+
| Z | a | p | h | o | d | 0 |   |  ...  |   |   |   | <- fullName
+---+---+---+---+---+---+---+---+--...--+---+---+---+

If fullname is able to hold 81 characters, and already contains “Zaphod” (6 characters, not counting the null), the maximum size of a string we could append would be 75 (81-6) characters. Remember that the null (0) character just marks the end of a C string, and gets overwritten by the next strcat() data.

This means what we really want is:

strncat( fullName, firstName, 75 );

Or do we? Actually, there’s another difference with strncat() versus strncpy(), and it was clearly stated in the function description:

Appends the first num characters of source to destination, plus a terminating null-character.

strncat() always appends the null (0) character, meaning if you gave it a long source string and told it to append up to 10 characters, it would append 10 characters plus the null (0) character. Thus, that 75 could actually append 76 characters! We have to always subtract one to avoid a buffer overrun.

// Copy up to 74 characters + null to the 81 character
// fullName buffer which already contains 6 characters.
strncat( fullName, firstName, 74 );

But hard-coding the numbers like that isn’t possible if we don’t know how many characters are already in the destination buffer. Instead, we can use some other C string calls to determine that and then do some math.

strlen() will return a count of how many characters are in a string buffer. It counts up to the first null (0) it finds. Thus, strlen(fullName) would return 6 (“Zaphod”). If we know the full size of the buffer, we can use strlen() to determine what is already there, and then simply subtract to know how many free bytes the buffer has. And since strncat() always adds a null, we subtract 1:

strncat( fullName, firstName, 81-strlen(fullName)-1 );

This is getting messy, but that is the basic way to ensure that strcat() doesn’t append too much data. Let’s update the original example a bit more:

#define FIRSTNAME_SIZE 40
#define LASTNAME_SIZE  40
// firstName + space + lastName
#define FULLANME_SIZE  FIRSTNAME_SIZE + 1 + LASTNAME_SIZE

char firstName[FIRSTNAME_SIZE];
char lastName[LASTNAME_SIZE];
char fullName[FULLNAME_SIZE]; 

// Load first name.
strncpy( firstName, "Zaphod", FIRSTNAME_SIZE-1 );
firstName[FIRSTNAME_SIZE-1] = '\0';

// Load last name.
strncpy( lastName, "Beeblebrox", LASTNAME_SIZE-1 );
lastName[LASTNAME_SIZE-1] = '\0';

// Create full name by starting with first name...
strncpy( fullName, firstName, FULLNAME_SIZE-1 );
fullName[FULLNAME_SIZE-1] = '\0';

// ...then appending a space...
strncat( fullName, " ", FULLNAME_SIZE-strlen(fullname)-1 );

// ...then appending the last name.
strncat( fullName, lastName, FULLNAME_SIZE-strlen(fullName)-1 );

So much extra code, but necessary to avoid a potential buffer overrun if the string being appended was passed in from another function where you don’t know the length.

Now we have a “safe” string append that can’t possibly write past the end of the destination buffer (fullName). If the string is too long, it just stops and puts a null there, truncating the string.

If every string copy is done using strncpy() to assure the destination buffer is never overran, and if every string append is done using strncat() with checks to limit how many characters can be appended, you practically eliminate the chance that a buffer overrun could occur and corrupt or crash your program.

However… If I were writing code to run a nuclear reactor, I might still take some extra steps to make sure the data I am using is valid.

Next time, we will look at a problem with this code. (Hint: What if something is wrong with the initial buffer that you are trying to append to?)

Until then…

See also: part 1, part 2, part 3, part 4, part 5 and part 6.

In part 1, I gave a quick overview of the C library call, strcpy(), and showed how it is used to copy a string in to a buffer.  I specifically wanted to show a problem that can happen if you copy more data than the buffer can hold (a buffer overrun), and show a simple way to fix it using strncpy().

The final example would limit how much data was copied to the number of bytes the buffer could hold:

char buffer[10];
strncpy( buffer, "I forgot how much room I have", 10);

Not only does strncpy() limit how many characters will be copied, it also does something else. If the source string is shorter than the maximum number you specify to copy, it pads the rest of the destination buffer with null characters (zeros). If you give it a null terminated string shorter than the max…

strncpy( buffer, "HI", 10);

…that would result in:

+---+---+---+---+---+---+---+---+---+---+
| H | I | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
+---+---+---+---+---+---+---+---+---+---+

Even though it’s clearly stated in the C library manual, I guess I never read that part. I had no idea it did that.

If I were to write my own crude implementation of strncpy(), it might look something like this:

// My own crude implementation of strncpy()
char * myStrncpy( char *destination, const char *source, size_t num )
{
size_t i;
// Now we will begin copying characters until we copy a null (0) or
// we have copied num characters.
for (i=0; i<num ; i++)
{
// If we have found a null character...
if (source[i]=='\0') break; // Exit the for loop.
// Copy a character over.
destination[i] = source[i];

}
// Here we have copied 'i' characters.
// If less than num, fill the rest with nulls.
while(i < num)
{
destination[i] = '\0';
i++;
}
return destination; // Why? Because it just does.
}




While strncpy() will prevent us from a buffer overrun, passing in a string that is too large will create a different problem: It will not leave us with a usable C string. Per the cplusplus.com page on strncpy:




No null-character is implicitly appended at the end of destination if source is longer than num. Thus, in this case, destination shall not be considered a null terminated C string (reading it as such would overflow).




strncpy() will copy characters until it has copied a null (0) or has copied a max number of bytes you specify with the third parameter. If you copy that full amount, and no null was copied, the destination buffer will not have a null terminator. It won't be a C string, and using it as one will do strange things.



char buffer[10];
strncpy( buffer, "I forgot how much room I have", 10);



+---+---+---+---+---+---+---+---+---+---+
| I |   | f | o | r | g | o | t |   | h |
+---+---+---+---+---+---+---+---+---+---+



In the above example, you end up with buffer full of 10 bytes of data without a null character at the end. You won't be able to use it with any of the C string functions like printf(), strlen(), strcat(), etc. Well, you can, but you might not get what you expect.



If you try to use it, these functions will continue through memory until they find the next null character after the buffer. If the next byte in memory after the buffer just happens to be a zero, everything will work and you won't see the problem. If the next 1K of memory is garbage that has NO zeros in it, the functions would begin at buffer and keep going as it if found a really long 1K string that starts out with what you expected, followed by garbage.



On operating systems that have memory protection, the program might even get terminated if it seeks through memory and ends up trying to read (still looking for that null byte) RAM that doesn't belong that that process.



Don't do that. Instead, when using strncpy(), always make sure you manually null terminate the buffer in case this situation occurs:



// Copy up to 10 characters.
strncpy( buffer, "I forgot how much room I have", 10);
// null terminate destination at 10th byte (bytes 0-9)
buffer[9] = '';




The end result of that will be up to 9 characters followed by a null. (See #3 below for an optimization tip.)



+---+---+---+---+---+---+---+---+---+---+
| I |   | f | o | r | g | o | t |   | 0 |
+---+---+---+---+---+---+---+---+---+---+



Because of needing a null at the end, if you truly did want a 10 character string, you would have to make the buffer 11 bytes large, so it can hold the 10 characters you want plus the null character at the end.



Therefore, my suggestion for doing string copies is to do the following:




For clarity, use a #define for how large the buffer is, so you have that define available to use in strncpy(). This will mean only one place in code to change the buffer size if you need to (rather than having to edit every function instance of strncpy() that used it).



Always manually null terminate the last byte of the destination buffer after the copy, just in case a string as large or larger than the buffer is copied to it. (Yes, this will add to your code and take more CPU time, but we are going for safety here.)



Optimization tip: Since you are going to manually terminate the final byte anyway, you can copy one less byte in strncpy(). (There is no need to have strncpy() write out to the final byte only to have you write to that final byte again.)




#define BUFSIZE 10
char buffer[BUFSIZE];
strncpy(buffer, "Here is my stuff", BUFSIZE-1);
buffer[BUFSIZE-1] = '';



Above, we will allow up to 9 bytes to be copied in to the buffer (BUFSIZE-1), then we will null terminate the 10th byte (remember bytes are numbered starting at zero, so 0-9, therefore BUFSIZE-1 is 9, the 10th byte of the buffer).



If you truly did want to be able to hold a 10 character string, just add one to the BUFSIZE define. None of the other code will have to be touched.



Get in to that simple habit and your strncpy() will now not create a buffer overflow, and will never create a non-terminated C string.



And before you say it . . .



Now, obviously, if YOU are copying a literal "string" inside your own code, you can know exactly how large it is so using strcpy() is perfectly safe (and more efficient if you don't need the rest of the destination buffer padded with zeros). BUT, if you code using strncpy() all the time, you will reduce the chances of you changing something later on that might cause you grief:



strcpy( buffer, "Game Over" );
...later changed to...
strcpy( buffer, "Game over, dude! You suck!" );




Above, a simple change to a message might end up crashing your program because you forgot how large buffer was.



In the next installment, we will take a look at strcat() and appending strings.

See also: part 1, part 2, part 3, part 4, part 5 and part 6.

I am pretty sure writing crash-proof code used to be a thing. Back when computers were simpler, and an entire project was done by one developer, it was much rarer to find a glaring bug in a piece of released software.

Today I’d like to share some things you may never have known, or thought about, when it comes to standard C library string manipulation calls.

Upon the conclusion of this series, you will know some very simple things to do to make your program a bit more crash proof just by using “safer” versions of C string calls. Let’s begin with the “less safe” calls.

From the very-useful cplusplus.com website:

• strcat( char *destination, const char *source ) – Concatenate strings. Appends a copy of the source string to the destination string. The terminating null character in destination is overwritten by the first character of source, and a null-character is included at the end of the new string formed by the concatenation of both in destination.
• strcpy( char *destination, const char *source ) – Copy string. Copies the C string pointed by source into the array pointed by destination, including the terminating null character (and stopping at that point).
  
  
  To avoid overflows, the size of the array pointed by destination shall be long enough to contain the same C string as source (including the terminating null character), and should not overlap in memory with source.
  
  

These simple functions allow us to copy, append and compare null terminated strings. A null is a zero that indicates the end of a string. Consider the string “HELLO WORLD”:

char *message = "HELLO WORLD";

In memory would be the characters “HELLO WORLD” followed by a 0 to indicate the end of the string:

+---+---+---+---+---+---+---+---+---+---+---+---+---+
| H | E | L | L | O |   | W | O | R | L | D | ! | 0 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+

When we control everything, and know exactly what we are doing, strings are safe. But in the real world, there are some very serious problems that can happen with strings that can cause crashes from memory corruption. At best, this may just be annoying if your Arduino sketch won’t run, but at worst, it could mean Armageddon if the corruption is on a system that controls nuclear missiles.

Let’s discuss some very simple habits to get in to when using strings in C that will reduce the chances of an atomic meltdown. Or your blinking LEDs from stopping blinking…

First, here is an example of the problem. Suppose you have a 10-byte string buffer:

char buffer[10];

Somewhere in memory will be 10 bytes reserved for that buffer:

+---+---+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |   |   | <- buffer
+---+---+---+---+---+---+---+---+---+---+

You can load a string in to that buffer using strcpy() like this:

strcpy( buffer, "HELLO" );

Then buffer will contain your string, including the null character at the end:

+---+---+---+---+---+---+---+---+---+---+
| H | E | L | L | O | 0 |   |   |   |   | <- buffer
+---+---+---+---+---+---+---+---+---+---+

Anything else in the buffer may be random junk from what might have been in that memory before the buffer was allocated. If this was a concern, we could have initialized that buffer memory ahead of time by doing something like this:

char buffer[10] = { 0 };

…or in your code, you could use memset() to clear the contents of the buffer:

memset( buffer, 0, 10 ); // Initialize buffer with zeros

But I digress. (Not to self: I should share some pros and cons of initializing data like that sometime.)

When you control the world, you can do things like this safely. But what if you forget how large buffer is, and try to load something larger in to it?

strcpy( buffer, "I forgot how much room I have" );

strcpy() will gladly start copying everything you give it up until it finds a null at the end of the string. In C, when you created a “quoted string” it automatically has a null added to the end of it.

Thus, it begins copying “I forgot how…” in to the 10 bytes of buffer, and keeps on going well past the end of buffer, overwriting whatever happens to be in memory past that area. This is a very common mistake.
Suppose you had created two buffers, and the compiler created them in memory next to each other:

char buffer[10];
char launchCode[10];

As the above strcpy() began writing to buffer, it would fill up buffer then continue to write over part of launchCode, corrupting whatever was there. This is bad, and you might not even notice if if you hadn’t checked launchCode to see if it was still intact.

+---+---+---+---+---+---+---+---+---+---+
| I |   | f | o | r | g | o | t |   | h | <- buffer
+---+---+---+---+---+---+---+---+---+---+
| o | w |   | m | u | c | h |   | r | o | <- launchCode
+---+---+---+---+---+---+---+---+---+---+
| o | m |   | I |   | h | a | v | e | 0 | ...other memory...
+---+---+---+---+---+---+---+---+---+---+

Worse, you might have had other types of variables there for counters, high scores or mom’s birthday, and overwriting the buffer might end up corrupting some numeric variable and cause your program to behave in unexpected ways. This can be madness to figure out :)

The solution is to use a special version of string copy that lets you specify the maximum number of characters it will copy before it stops.

• strncpy( char *destination, const char *source, size_t num ) – Copy characters from string. Copies the first num characters of source to destination. If the end of the source C string (which is signaled by a null-character) is found before num characters have been copied, destination is padded with zeros until a total of numcharacters have been written to it.
  
  No null-character is implicitly appended at the end of destination if source is longer than num. Thus, in this case,destination shall not be considered a null terminated C string (reading it as such would overflow).
  
  destination and source shall not overlap (see memmove for a safer alternative when overlapping).
  
  

By using this, and specifying the max size of the destination buffer, we can prevent the overrun and life will be perfect and happy:

strncpy( buffer, "I forgot how much room I have", 10 );

…or will it?

+---+---+---+---+---+---+---+---+---+---+
| I |   | f | o | r | g | o | t |   | h | <- buffer
+---+---+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |   |   | <- launchCode
+---+---+---+---+---+---+---+---+---+---+

That looks fine, doesn’t it?

In the next part, I’ll demonstrate why the above example is bad, and show you an easy way to make it more bullet-proof. Maybe you see it already… (Hint: The description of strncpy specifically mentions the problem.)

I’ll also discuss appending strings with strcat() and the similar problems that happen there, plus a few unexpected things I did not realize about these functions until I was digging in to them this week for a work project.

To be continued…