-
Notifications
You must be signed in to change notification settings - Fork 87
API Reference
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()
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()
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()
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()
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
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()
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 );
}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()
###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()
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()