Skip to content

API Reference

Jump to bottom
Dave W edited this page Apr 25, 2016 · 28 revisions

API Reference Pages

NAME: strcpy_s

SYNOPSIS:

     #include "safe_mem_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: strncat_s

SYNOPSIS:

     #include "safe_mem_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:

NAME: strnlen_s

SYNOPSIS:

     #include "safe_mem_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: 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: 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()

Clone this wiki locally