JTC1/SC22/WG14 N1110

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 <string.h>

    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 <string.h>

    /* ... */

    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)).