Skip to content

API Reference

Jump to bottom
Dave W edited this page Feb 21, 2019 · 28 revisions

API Reference Pages

NAME: strcpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     strcpy_s(char *dest, rsize_t dmax, const char *src)

DESCRIPTION:
The strcpy_s function copies the string pointed to by src (including the terminating null character) into the array pointed to by dest. All elements following the terminating null character (if any) written by strcpy_s in the array of dmax characters pointed to by dest are nulled when strcpy_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.

  dmax      restricted maximum length of dest

  src       pointer to the string that will be copied to dest

OUTPUT PARAMETERS:
dest updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • dmax shall not be greater than RSIZE_MAX_STR.
  • dmax shall not equal zero.
  • dmax shall be greater than strnlen_s(src, dmax).
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and destmax is greater than zero and not greater than RSIZE_MAX_STR, then strcpy_s nulls dest.

RETURN VALUE:

  • EOK successful operation, the characters in src were copied into dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

ALSO SEE:
strcat_s(), strncat_s(), strncpy_s()

NAME: strncpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     strncpy_s(char *dest, rsize_t dmax, const char *src, rsize_t slen)

DESCRIPTION:
The strncpy_s function copies not more than slen successive characters (characters that follow a null character are not copied) from the array pointed to by src to the array pointed to by dest. If no null character was copied from src, then dest[n] is set to a null character.
All elements following the terminating null character (if any) written by strncpy_s in the array of dmax characters pointed to by dest take on the null value when strncpy_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to string that will be replaced by src.
           The resulting string is null terminated.

 dmax      restricted maximum length of the resulting dest,
           including the null

 src       pointer to the string that will be copied
           to string dest

 slen      the maximum number of characters to copy from src

OUTPUT PARAMETERS:
dest updated with src string

RUNTIME CONSTRAINTS:

  • Neither dmax nor slen shall be equal to zero.
  • Neither dmax nor slen shall be equal zero.
  • Neither dmax nor slen shall be greater than RSIZE_MAX_STR.
  • If slen is either greater than or equal to dmax, then dmax should be more than strnlen_s(src,dmax)
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax greater than RSIZE_MAX_STR, then strncpy_s nulls dest.

RETURN VALUE:

  • EOK successful operation, the characters in src were copied to dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

ALSO SEE:
strcat_s(), strncat_s(), strcpy_s()

NAME: stpcpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     char *
     stpcpy_s(char *dest, rsize_t dmax, const char *src, errno_t *err);

DESCRIPTION:
The stpcpy_s function copies the string pointed to by src (including the terminating null character) into the array pointed to by dest. All elements following the terminating null character (if any) written by stpcpy_s in the array of dmax characters pointed to by dest are nulled when strcpy_s returns. The function returns a pointer to the end of the string in dest - that is to the null terminator of dest - upon return. If an error occurs, NULL is returned and err is set to the error encountered.

EXTENSION TO:
This extension is added to complement the specification of strcpy_s.

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.

  dmax      restricted maximum length of dest

  src       pointer to the string that will be copied to dest

  err      the error code upon error, or EOK if successful

OUTPUT PARAMETERS:
dest updated
err updated as follows:

  • EOK successful operation, the characters in src were copied into dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • dmax shall not be greater than RSIZE_MAX_STR.
  • dmax shall not equal zero.
  • dmax shall be greater than strnlen_s(src, dmax).
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and destmax is greater than zero and not greater than RSIZE_MAX_STR, then stpcpy_s nulls dest.

RETURN VALUE:
a char pointer to the terminating null at the end of dest

ALSO SEE:
strcpy_s(), strcat_s(), strncat_s(), strncpy_s()

NAME: stpncpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     char *
     stpncpy_s(char *dest, rsize_t dmax, const char *src, rsize_t smax, errno_t *err);

DESCRIPTION:
The stpncpy_s function copies at most smax characters from the string pointed to by src, including the terminating null byte ('\0'), to the array pointed to by dest. Exactly smax characters are written at dest. If the length strlen_s(src) is smaller than smax, the remaining smax characters in the array pointed to by dest are filled with null bytes. If the length strlen_s(src) is greater than or equal to smax, the string pointed to by dest will contain smax characters from src plus a null characters (dest will be null-terminated).
Therefore, dmax must be at least smax+1 in order to contain the terminator.
The function returns a pointer to the end of the string in dest - that is to the null terminator of dest. If an error occurs, NULL is returned and err is set to the error encountered.

EXTENSION TO:
This extension is added to complement the specification of strcpy_s and stpcpy_s.

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.

  dmax      restricted maximum length of dest (must be at least smax+1)

  src       pointer to the string that will be copied to dest

  smax      the maximum number of characters from src to copy into dest

  err       the error code upon error, or EOK if successful

OUTPUT PARAMETERS:
dest updated
err updated as follows:

  • EOK successful operation, the characters in src were copied into dest, the result is null terminated, and dest is returned to point to the first null at end of dest
  • On error, NULL is returned and err is set to one of the following:
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • dmax shall not be greater than RSIZE_MAX_STR.
  • dmax shall not equal zero.
  • dmax must be at least smax+1 to allow filling dest with smax characters plus NULL.
  • If src and dest overlap, copying shall be stopped; destruction of src may have occurred.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then stpncpy_s shall fill dest with nulls if library was compiled with SAFECLIB_STR_NULL_SLACK.

RETURN VALUE:
a char pointer to the terminating null at the end of dest, or NULL pointer on error

ALSO SEE:
stpcpy_s(), strcpy_s(), strcat_s(), strncat_s(), strncpy_s()

NAME: strcat_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     strcat_s(char *dest, rsize_t dmax, const char *src)

DESCRIPTION:
The strcat_s function appends a copy of the string pointed to by src (including the terminating null character) to the end of the string pointed to by dest. The initial character from src overwrites the null character at the end of dest.
All elements following the terminating null character (if any) written by strcat_s in the array of dmax characters pointed to by dest take unspecified values when strcat_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to string that will be extended by src
          if dmax allows. The string is null terminated.
          If the resulting concatenated string is less
          than dmax, the remaining slack space is nulled.

 dmax      restricted maximum length of the resulting dest,
           including the null

 src       pointer to the string that will be concatenaed
           to string dest

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer
  • dmax shall not equal zero
  • dmax shall not be greater than RSIZE_STR_MAX
  • dmax shall be greater than strnlen_s(src,m).
  • Copying shall not take place between objects that overlap
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX, then strcat_s nulls dest.

RETURN VALUE:

  • EOK        successful operation, all the characters from src were appended to dest and the result in dest is null terminated.

  • ESNULLP    NULL pointer

  • ESZEROL    zero length

  • ESLEMAX    length exceeds max limit

  • ESUNTERM   dest not terminated

ALSO SEE:
strncat_s(), strcpy_s(), strncpy_s()

NAME: strncat_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     strncat_s(char *dest, rsize_t dmax, const char *src, rsize_t slen)

DESCRIPTION:
The strncat_s function appends a copy of the string pointed to by src (including the terminating null character) to the end of the string pointed to by dest. The initial character from src overwrites the null character at the end of dest.
All elements following the terminating null character (if any) written by strncat_s in the array of dmax characters pointed to by dest take unspecified values when strncat_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to string that will be extended by src
          if dmax allows. The string is null terminated.
          If the resulting concatenated string is less
          than dmax, the remaining slack space is nulled.

 dmax      restricted maximum length of the resulting dest,
           including the null

 src       pointer to the string that will be concatenaed
           to string dest

 slen      maximum characters to append

OUTPUT PARAMETERS:
dest updated string

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer
  • dmax shall not equal zero
  • dmax shall not be greater than RSIZE_STR_MAX
  • dmax shall be greater than strnlen_s(src,m).
  • Copying shall not takeplace between objects that overlap
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater thanRSIZE_MAX, then strncat_s sets dest[0] to the null character.

RETURN VALUE:

  • EOK        successful operation, all the characters from src were appended to dest and the result in dest is null terminated.

  • ESNULLP    NULL pointer

  • ESZEROL    zero length

  • ESLEMAX    length exceeds max limit

  • ESUNTERM   dest not terminated

ALSO SEE:
strcat_s

NAME: wcscat_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     wcscat_s(wchar_t* dest, rsize_t dmax, const wchar_t* src)

DESCRIPTION:
The wcscat_s function appends a copy of the wide character string pointed to by src (including the terminating null character) to the end of the string pointed to by dest. The initial wide character from src overwrites the null character at the end of dest.
All elements following the terminating null character (if any) written by wcscat_s in the array of dmax characters pointed to by dest take unspecified values when wcscat_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to wide character string that will be extended by src
          if dmax allows. The string is null terminated.
          If the resulting concatenated string is less
          than dmax, the remaining slack space is nulled.

 dmax      restricted maximum length of the resulting dest,
           including the null

 src       pointer to the string that will be concatenated
           to string dest

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer
  • dmax shall not equal zero
  • dmax shall not be greater than RSIZE_STR_MAX
  • dmax shall be greater than wcsnlen_s(src,m).
  • Copying shall not take place between objects that overlap
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX, then wcscat_s nulls dest.

RETURN VALUE:

  • EOK        successful operation, all the characters from src were appended to dest and the result in dest is null terminated.

  • ESNULLP    NULL pointer

  • ESZEROL    zero length

  • ESLEMAX    length exceeds max limit

  • ESUNTERM   dest not terminated

ALSO SEE:
strcat_s, strncat_s(), strcpy_s(), strncpy_s()

NAME: wcsncat_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     wcsncat_s(wchar_t *dest, rsize_t dmax, const wchar_t *src, rsize_t slen)

DESCRIPTION:
The wcsncat_s function appends a copy of (at most) the first slen wide characters pointed to by src to the end of the string pointed to by dest and terminates the string with the null character. If less than slen wide characters are in the string src, the function stops copying after the null terminator is copied to dest. The initial character from src overwrites the null character at the end of dest.
All elements following the terminating null character (if any) written by strncat_s in the array of dmax characters pointed to by dest take unspecified values when strncat_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to string that will be extended by src
          if dmax allows. The string is null terminated.
          If the resulting concatenated string is less
          than dmax, the remaining slack space is nulled.

max       restricted maximum length of the resulting dest,
          including the null

src       pointer to the string that will be concatenated
          to string dest

slen      maximum characters to append

OUTPUT PARAMETERS:
dest updated string

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer
  • dmax shall not equal zero
  • dmax shall not be greater than RSIZE_STR_MAX
  • dmax shall be greater than wcsnlen_s(src,m).
  • Copying shall not take place between objects that overlap
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX, then wcsncat_s sets dest[0] to the null character.

RETURN VALUE:

  • EOK        successful operation, all the characters from src were appended to dest and the result in dest is null terminated.

  • ESNULLP    NULL pointer

  • ESZEROL    zero length

  • ESLEMAX    length exceeds max limit

  • ESUNTERM   dest not terminated

ALSO SEE:
strcat_s, strncat_s, wcscat_s

NAME: strnlen_s

SYNOPSIS:

     #include "safe_str_lib.h"
     rsize_t
     strnlen_s(const char *dest, rsize_t dmax)

DESCRIPTION:
The strnlen_s function computes the length of the string pointed to by dest.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to string

dmax      restricted maximum length

OUTPUT PARAMETERS:
none

RUNTIME CONSTRAINTS:

  • dest shall not be a null pointer
  • dmax shall not be greater than RSIZE_MAX_STR
  • dmax shall not equal zero

RETURN VALUE:
The function returns the string length, excluding the terminating null character. If dest is NULL, then strnlen_s returns 0.
Otherwise, the strnlen_s function returns the number of characters that precede the terminating null character. If there is no null character in the first dmax characters of dest then strnlen_s returns dmax. At most the first dmax characters of dest are accessed by strnlen_s.

ALSO SEE:
strnterminate_s()

NAME: strtok_s

SYNOPSIS:

     #include "safe_str_lib.h"
     char *
     strtok_s(char *dest, rsize_t *dmax, char *src, char **ptr)

DESCRIPTION:
A sequence of calls to the strtok_s function breaks the string pointed to by dest into a sequence of tokens, each of which is delimited by a character from the string pointed to by src. The fourth argument points to a caller-provided char pointer into which the strtok_s function stores information necessary for it to continue scanning the same string.
The first call in a sequence has a non-null first argument and dmax points to an object whose value is the number of elements in the character array pointed to by the first argument. The first call stores an initial value in the object pointed to by ptr and updates the value pointed to by dmax to reject the number of elements that remain in relation to ptr. Subsequent calls in the sequence have a null first argument and the objects pointed to by dmax and ptr are required to have the values stored by the previous call in the sequence, which are then updated. The separator string pointed to by src may be different from call to call.
The first call in the sequence searches the string pointed to by dest for the first character that is not contained in the current separator string pointed to by src. If no such character is found, then there are no tokens in the string pointed to by dest and the strtok_s function returns a null pointer. If such a character is found, it is the start of the first token.
The strtok_s function then searches from there for the first character in dest that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by dest, and subsequent searches in the same string for a token return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token.
In all cases, the strtok_s function stores sufficient information in the pointer pointed to by ptr so that subsequent calls, with a null pointer for dest and the unmodified pointer value for ptr, shall start searching just past the element overwritten by a null character (if any).

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

  dest      pointer to string to tokenize

  dmax      restricted maximum length of dest string

  src       pointer to delimiter string (len < 255)

  ptr       returned pointer to token

OUTPUT PARAMETERS:
dmax update length
ptr update pointer to token

RUNTIME CONSTRAINTS:

  • src shall not be a null pointer.
  • ptr shall not be a null pointer.
  • dmax shall not be a null pointer.
  • *dmax shall not be 0.
  • If dest is a null pointer, then *ptr shall not be a null pointer.
  • dest must not be unterminated.
  • The value of *dmax shall not be greater than RSIZE_MAX_STR. The end of the token found shall occur within the first *dmax characters of dest for the first call, and shall occur within the first *dmax characters of where searching resumes on subsequent calls.

RETURN VALUE:
The strtok_s function returns a pointer to the first character of a token; or a null pointer if there is no token or there is a runtime-constraint violation.

  • EOK

  • ESNULLP     NULL pointer

  • ESZEROL     zero length

  • ESLEMAX     length exceeds max limit

  • ESUNTERM    unterminated string

ALSO SEE:
none

EXAMPLES:
[1] Sequencial strtok_s() calls to tokenize a string

     // String to tokenize 
     str1 = ",.:*one,two;three,;four*.*.five-six***";   // len=38
     
     // String of delimiters 
     str2 = ",.;*";
 
     p2tok = strtok_s(str1, &len, str2, &p2str);
     // token -one-  remaining -two;three,;four*.*.five-six***- len=30
 
     p2tok = strtok_s(NULL, &len, str2, &p2str);
     // token -two-  remaining -three,;four*.*.five-six***- len=26
 
     p2tok = strtok_s(NULL, &len, str2, &p2str);
     // token -three-  remaining -;four*.*.five-six***- len=20
 
     p2tok = strtok_s(NULL, &len, str2, &p2str);
     // token -four-  remaining -.*.five-six***- len=14
 
     p2tok = strtok_s(NULL, &len, str2, &p2str);
     // token -five-six-  remaining -**- len=2
 
     p2tok = strtok_s(NULL, &len, str2, &p2str);
     // token -(null)-  remaining -**- len=0

[2] While loop with same entry data as [1]

     p2tok = str1;
     while (p2tok && len) {
         p2tok = strtok_s(NULL, &len, str2, &p2str);
         printf("  token --   remaining --  len=0 \n",
                 p2tok, p2str, (int)len );
     }

NAME: memcmp_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     memcmp_s(const void *dest, rsize_t dmax,
              const void *src,  rsize_t smax, int *diff)

DESCRIPTION:
Compares memory until they differ, and their difference is returned in diff.
If the block of memory is the same, diff=0.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to memory to compare against

dmax      maximum length of dest, in bytes

src       pointer to the source memory to compare with dest

smax      length of the source memory block

diff      pointer to the diff which is an integer greater than, equal to or less than zero according to
          whether the object pointed to by dest is greater than, equal to or less than the object
          pointed to by src.

OUTPUT PARAMETERS:
none

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor smax shall be zero.
  • dmax shall not be greater than RSIZE_MAX_MEM.
  • smax shall not be greater than dmax.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit

ALSO SEE:
memcmp16_s(), memcmp32_s()

NAME: wmemcmp_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     wmemcmp_s(const wchar_t *dest, rsize_t dmax,
               const wchar_t *src,  rsize_t smax, int *diff)

DESCRIPTION:
Compares wide-character strings until they differ, and their difference is returned in diff. If the wide character string is the same, diff=0.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to memory to compare against

dmax      maximum length of dest, in uint32_t

src       pointer to the source memory to compare with dest

smax      length of src, in uint32_t

*diff pointer to the diff which is an integer greater than, equal to or less than zero according to whether the object pointed to by dest is greater than, equal to or less than the object pointed to by src.

OUTPUT PARAMETERS:
none

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor smax shall be zero.
  • dmax shall not be greater than RSIZE_MAX_MEM.
  • smax shall not be greater than dmax.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit

ALSO SEE:
memcmp_s(), memcmp16_s(), memcmp32_s()

NAME: memcpy_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     memcpy_s(void *dest, rsize_t dmax, const void *src, rsize_t smax)

DESCRIPTION:
This function copies at most smax bytes from src to dest, up to dmax.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to memory that will be replaced by src.

 dmax      maximum length of the resulting dest

 src       pointer to the memory that will be copied to dest

 smax      maximum number bytes of src to copy

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor smax shall be zero.
  • dmax shall not be greater than RSIZE_MAX_MEM.
  • smax shall not be greater than dmax.
  • Copying shall not take place between regions that overlap.
  • If there is a runtime-constraint violation, the memcpy_s function stores zeros in the ï¬�rst dmax bytes of the region pointed to by dest if dest is not a null pointer and smax is valid.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP source memory overlaps destination

ALSO SEE:
memcpy16_s(), memcpy32_s(), memmove_s(), memmove16_s(), memmove32_s()

NAME: wmemcpy_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     wmemcpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, rsize_t smax)

DESCRIPTION:
This function copies at most smax wide characters from src to dest, up to dmax.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to memory that will be replaced by src.

 dmax      maximum length of the resulting dest

 src       pointer to the memory that will be copied to dest

 smax      maximum number of wide characters of src to copy

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor smax shall be zero.
  • dmax shall not be greater than RSIZE_MAX_MEM.
  • smax shall not be greater than dmax.
  • Copying shall not take place between regions that overlap.
  • If there is a runtime-constraint violation, the wmemcpy_s function stores zeros in the first dmax wide characters of the region pointed to by dest, if dest is not a null pointer, and smax is valid.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP source memory overlaps destination

ALSO SEE:
memcpy16_s(), memcpy32_s(), memmove_s(), memmove16_s(), memmove32_s(), memcpy_s(), wmemmove_s()

NAME: memmove_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     memmove_s(void *dest, rsize_t dmax, const void *src, rsize_t smax)

DESCRIPTION:
The memmove_s function copies smax bytes from the region pointed to by src into the region pointed to by dest. This copying takes place as if the smax bytes from the region pointed to by src are first copied into a temporary array of smax bytes that does not overlap the region pointed to by dest or src, and then the smax bytes from the temporary array are copied into the object region to by dest.
This function differs from memcpy_s in that it allows overlap between src and dest buffers.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to memory that will be replaced by src.

 dmax      maximum length of the resulting dest, in bytes

 src       pointer to the memory that will be copied to dest

 smax      maximum number bytes of src that can be copied

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor smax shall be zero.
  • dmax shall not be greater than RSIZE_MAX_MEM.
  • smax shall not be greater than dmax.
  • If there is a runtime-constraint violation, the memmove_s function stores zeros in the first dmax characters of the region pointed to by dest, if dest is not a null pointer, and dmax is not greater than RSIZE_MAX_MEM.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit

ALSO SEE:
memmove16_s(), memmove32_s(), memcpy_s(), memcpy16_s(), memcpy32_s()

NAME: wmemmove_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     wmemmove_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, size_t smax)

DESCRIPTION:
The wmemmove_s function copies smax wide characters from the region pointed to by src into the region pointed to by dest. This copying takes place as if the smax wide characters from the region pointed to by src are first copied into a temporary array of smax wide characters that does not overlap the region pointed to by dest or src, and then the smax wide characters from the temporary array are copied into the object region to by dest.
This function differs from memcpy_s in that it allows overlap between src and dest buffers.
This function differs from memmove_s in that it copies wide characters instead of bytes.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to memory that will be replaced by src.

 dmax      maximum length of resulting wide characters in dest

 src       pointer to the memory that will be copied to dest

 smax      maximum number of wide characters of src that can be copied

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor smax shall be zero.
  • dmax shall not be greater than RSIZE_MAX_MEM/sizeof(wchar_t).
  • smax shall not be greater than dmax.
  • If there is a runtime-constraint violation, the memmove_s function stores zeros in the first dmax characters of the region pointed to by dest, if dest is not a null pointer, and dmax is not greater than RSIZE_MAX_MEM/sizeof(wchar_t).

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit

ALSO SEE:
wmemcpy_s(), memmove16_s(), memmove32_s(), memcpy_s(), memcpy16_s(), memcpy32_s()

NAME: memset_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     memset_s(void *dest, rsize_t len, uint8_t value)

DESCRIPTION:
The memset_s function sets len bytes starting at dest to the specified value.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to memory that will be set to the value.

 len       number of bytes to be set

 value     byte value

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • dest shall not be a null pointer.
  • len shall not be zero or greater than RSIZE_MAX_MEM.
  • If there is a runtime-constraint violation, the operation is not performed.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit

ALSO SEE:
memset16_s(), memset32_s()

NAME: wmemset_s

SYNOPSIS:

     #include "safe_mem_lib.h"
     errno_t
     wmemset_s(wchar_t *dest, wchar_t value, rsize_t len)

DESCRIPTION:
The wmemset_s function sets len number of wide characters starting at dest to the specified value.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

 dest      pointer to memory that will be set to the value.

 value     byte value

 len       number of wide characters to be set

OUTPUT PARAMETERS:
dest is updated

RUNTIME CONSTRAINTS:

  • dest shall not be a null pointer.
  • len shall not be zero or greater than RSIZE_MAX_MEM/sizeof(wchar_t).
  • If there is a runtime-constraint violation, the operation is not performed.

RETURN VALUE:

  • EOK successful operation
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit

ALSO SEE:
memset_s(), memset16_s(), memset32_s()

NAME: wcsnlen_s

SYNOPSIS:

     #include "safe_str_lib.h"
     rsize_t
     wcsnlen_s(const wchar_t *dest, rsize_t dmax)

DESCRIPTION:
The wcsnlen_s function computes the length of the wide character string pointed to by dest.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

dest      pointer to wide character string

dmax      restricted maximum length

OUTPUT PARAMETERS:
none

RUNTIME CONSTRAINTS:

  • dest shall not be a null pointer
  • dmax shall not be greater than RSIZE_MAX_STR
  • dmax shall not equal zero

RETURN VALUE:
The function returns the number of wide characters in the string pointed to by dest, excluding the terminating null character. If dest is NULL, then wcsnlen_s returns 0.
Otherwise, the wcsnlen_s function returns the number of wide characters that precede the terminating null character. If there is no null character in the first dmax characters of dest then wcsnlen_s returns dmax. At most the first dmax characters of dest are accessed by wcsnlen_s.

ALSO SEE:
strnlen_s, strnterminate_s()

NAME: wcscpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     wcscpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src)

DESCRIPTION:
The wcscpy_s function copies the wide character string pointed to by src (including the terminating null character) into the array pointed to by dest. All elements following the terminating null character (if any) written by strcpy_s in the array of dmax characters pointed to by dest are nulled when wcscpy_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.

  dmax      restricted maximum length of dest

  src       pointer to the wide character string that will be copied to dest

OUTPUT PARAMETERS:
dest updated

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • dmax shall not be greater than RSIZE_MAX_STR.
  • dmax shall not equal zero.
  • dmax shall be greater than wcsnlen_s(src, dmax).
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and destmax is greater than zero and not greater than RSIZE_MAX_STR, then wcscpy_s nulls dest.

RETURN VALUE:

  • EOK successful operation, the characters in src were copied into dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

ALSO SEE:
strcpy_s, strcat_s(), strncat_s(), strncpy_s(), wcscat_s()

NAME: wcsncpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     errno_t
     wcsncpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, rsize_t slen)

DESCRIPTION:
The wcsncpy_s function copies not more than slen successive characters (characters that follow a null character are not copied) from the array pointed to by src to the array pointed to by dest. If no null character was copied from src, then dest[slen] is set to a null character.
All elements following the terminating null character (if any) written by wcsncpy_s in the array of dmax characters pointed to by dest take on the null value when wcsncpy_s returns.
When SAFECLIB_STR_NULL_SLACK is defined to be true (#DEFINE), then the dest array is filled with NULL characters following the end of the last non-NULL character from src. While this is more secure, it is also incurs a performance penalty, especially when the same dest array is used multiple times with string manipulation routines in this library. If this extra security is not required, ensure that the library is compiled without #DEFINE SAFECLIB_STR_NULL_SLACK.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.
            The resulting string is null terminated.

  dmax      restricted maximum length of the resulting dest
            including the null 

  src       pointer to the wide character string that will be copied to dest

  slen      the maximum number of wide characters to copy from src.

OUTPUT PARAMETERS:
dest updated with sec string

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor slen shall be equal to zero.
  • Neither dmax nor slen shall be greater than RSIZE_MAX_STR.
  • If slen is either greater than or equal to dmax, then dmax should be more than wcsnlen_s(src,dmax)
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcsncpy_s nulls dest.

RETURN VALUE:

  • EOK successful operation, the characters in src were copied into dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

ALSO SEE:
strcpy_s, strcat_s(), strncat_s(), strncpy_s(), wcscat_s(), wcsncat_s(), wcscpy_s()

NAME: wcpcpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     wchar_t *
     wcpcpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, errno_t *err)

DESCRIPTION:
The wcpcpy_s function copies the wide character string pointed to by src (including the terminating null character) into the array pointed to by dest, and returns a pointer to the end of the wide character string. All elements following the terminating null character (if any) written by wcpcpy_s in the array of dmax characters pointed to by dest are nulled when wcpcpy_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.

  dmax      restricted maximum length of dest

  src       pointer to the wide character string that will be copied to dest

  err       the error code upon error, or EOK if successful

OUTPUT PARAMETERS:
dest updated
err updated as follows:

  • EOK successful operation, the characters in src were copied into dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • dmax shall not be greater than RSIZE_MAX_STR.
  • dmax shall not equal zero.
  • dmax shall be greater than wcsnlen_s(src, dmax).
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcpcpy_s nulls dest.

RETURN VALUE:
a wchar_t pointer to the terminating null at the end of dest

ALSO SEE:
wcscpy_s(), wcscat_s(), wcsncat_s(), wcsncpy_s()
strpcpy_s(), strcpy_s, strcat_s(), strncat_s(), strncpy_s(), wcscat_s()

NAME: wcpncpy_s

SYNOPSIS:

     #include "safe_str_lib.h"
     wchar_t *
     wcpncpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, rsize_t slen, errno_t *err)

DESCRIPTION:
The wcpncpy_s function copies not more than slen successive wide characters (characters that follow a null character are not copied) from the array pointed to by src (including the terminating null character) into the array pointed to by dest, and returns a pointer to the end of the wide character string. If no null character was copied from src, then dest[slen] is set to a null character.
All elements following the terminating null character (if any) written by wcpncpy_s in the array of dmax characters pointed to by dest are nulled when wcpncpy_s returns.

EXTENSION TO:
ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software
interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

INPUT PARAMETERS:

  dest      pointer to string that will be replaced by src.
            The resulting string is null terminated.

  dmax      restricted maximum length of the resulting dest
            including the null 

  src       pointer to the wide character string that will be copied to dest

  slen      the maximum number of wide characters to copy from src.

  err       the error code upon error, or EOK if successful

OUTPUT PARAMETERS:
dest updated
err updated as follows:

  • EOK successful operation, the characters in src were copied into dest and the result is null terminated.
  • ESNULLP NULL pointer
  • ESZEROL zero length
  • ESLEMAX length exceeds max limit
  • ESOVRLP strings overlap
  • ESNOSPC not enough space to copy src

RUNTIME CONSTRAINTS:

  • Neither dest nor src shall be a null pointer.
  • Neither dmax nor slen shall be equal to zero.
  • Neither dmax nor slen shall be greater than RSIZE_MAX_STR.
  • If slen is either greater than or equal to dmax, then dmax should be more than wcsnlen_s(src,dmax)+wcsnlen_s(dest,dmax)
  • Copying shall not take place between objects that overlap.
  • If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcpncpy_s nulls dest.

RETURN VALUE:
a wchar_t pointer to the terminating null at the end of dest

ALSO SEE:
wcpcpy_s(), wcscpy_s(), wcscat_s(), wcsncat_s(), wcsncpy_s()
strpcpy_s(), strcpy_s, strcat_s(), strncat_s(), strncpy_s(), wcscat_s()

Clone this wiki locally