WG14 Document: N1110 Date: 2005-03-09 ---------------------------------------------------------------------------------- Title: Overflow Protected String Building Author: Peter van der Veen Author Affiliation: QNX Software Systems Ltd. Postal Address: 175 Terence Matthews Cr. E-mail Address: peterv@qnx.com Telephone Number: +1 613 591-0931 Fax Number: +1 613 591-3579 Sponsor: Date: March 9, 2005 Document History: New proposal based on on-line discussion about Secure C Functions Proposal Category: X New API Area of standard Affected: X Language Prior Art: QNX Neutrino (A real-time POSIX operating system) Target Audience: programmers who need to safely build strings Proposal Attached: X Yes Abstract: The straddstr() function adds str to the buffer pointed to by pbuf, respecting the maximum length indicated by pmaxbuf. The values of pbuf and pmaxlen are updated. Proposal: straddstr() - Concatenate one string on to the end of another Synopsis: #include int straddstr(const char *str, int len, char **pbuf, size_t *pmaxbuf); Arguments: str - The string that you want to add to the end of another. len - The number of characters from str that you want to add. If zero, the function adds all of str. pbuf - The address of a pointer to the destination buffer that will be updated. pmaxbuf - A pointer to the size of the destination buffer that will be updated. Library: libc Description: The straddstr function copies not more than the minimum of the size_t that pmaxbuf points to or len successive characters (characters that follow a null character are not copied) from the array pointed to by the character pointer that pbuf points to. The character pointer that pbuf points to will be updated to point to the end of the actual copied characters and the size_t that pmaxbuf points to will be decremented by the actual copied characters. The returned value is the number of characters in the passed in str even if the number of actual characters was less. If size_t that pmaxbuf points to was greater than zero on entring the function, then the character that is pointed to by the character pointer pbuf will always be ‘\0’ on return. If len was passed in as a 0 then the length is calculated as if strlen was called on str. Example: This function can be called many consecutivly to safely build a string. The string will always be null terminated even if the source strings do not fit into the destination buffer. #include /* ... */ int myfunc(char *buf, size_t bufsize) { int len = straddstr("string1", 0, &buf, &bufsize); len += straddstr("string2?????", 7, &buf, &bufsize); len += straddstr("string3", 10, &buf, &bufsize); return len; } /* ... */ char buf1[10], buf2[100]; int len1 = myfunc(buf1, sizeof buf1); int len2 = myfunc(buf2, sizeof buf2); In the example the myfunc function will always return 21, the desired size of the buffer to contain all of the strings, but the buffer will only contain up to bufsiz-1 of the character strings always terminating resulting string with a ‘\0’ character. In this example len1 == len2 == 21 and buf1 will contain "string1st\0" and buf2 will contain "string1string2string3\0???...???" where the characters after the ‘\0’ are not touched. The values of buf and bufsize in the first invocation of myfunc() with an original size of 10 would be before: &original_buf[0] bufsize=10 after 1st: &original_buf[7] bufsize=3 after 2nd: &original_buf[9] bufsize=1 after 3rd: &original_buf[9] bufsize=1 The values of buf and bufsize in the second invocation of myfunc() with an original size of 100 would be before: &original_buf[0] bufsize=100 after 1st: &original_buf[7] bufsize=93 after 2nd: &original_buf[14] bufsize=86 after 3rd: &original_buf[21] bufsize=79 Returns: The value of len if it's nonzero; otherwise, the length of str (i.e. strlen(str)).