The <string.h> header file


  
This header file contains the following functions:
_memset              memchr               memcmp               memcpy
memmove              memset               sprintf              strcat
strchr               strcmp               strcpy               strcspn
strerror             strlen               strncat              strncmp
strncpy              strpbrk              strrchr              strspn
strstr               strtok
and the following constants and predefined types:
NULL                 size_t

Functions


short sprintf (char *buffer, const char *format, ...);

Sends formatted output to a string.

sprintf sends formatted output to a string. In fact, it does the following: sprintf applies the first format specifier to the first argument, the second to the second, and so on. The format string, controls how sprintf will convert and format its arguments. There must be enough arguments for the format; if there are not, the results will be unpredictable and likely disastrous. Excess arguments (more than required by the format) are merely ignored. The format string is a character string that contains two types of objects: plain characters and conversion specifications. Plain characters are simply copied verbatim to the output string. Conversion specifications fetch arguments from the argument list and apply formatting to them. sprintf format specifiers have the following form:

% [flags] [width] [.prec] [{h|l}] type

Here is a complete table of supported formatting options (see any book about C language for more info):

FlagsMeaning
noneRight align (pad spaces or zeros to left)
-Left align (pad spaces to right)
+Always force sign (include prefix '+' before positive values)
zDon't postfix padding (this option is non-ANSI, i.e. TI specific)
spaceInsert space before positive values
#Prefix octal values with 0 and hex values (>0) with '0x')
Force '.' in float output (and prevent trunctation of trailing zeros)
^TI-Float format: special character for the exponent and for the minus sign, no '+' prefix in the exponent, 0. instead of 0, no leading zeros if the magnitude is smaller than 1 (this option is non-ANSI, i.e. TI specific)
|Centre the output in the field (this option is non-ANSI, i.e. TI specific)


WidthMeaning
numPrint at least num characters - padded the rest with blanks
0num(Zero prefixed) Same as above but padded with '0'
*The width is specified in the arguments list (before value being formatted)


PrecisionMeaning
noneDefault precision
numnum is number of chars, decimal places, or number of significant digits (num<=16) to display depending on type (see below)
-1Default = 6 digits (this option is non-ANSI, i.e. TI specific)
*The precision is specified in the argument list (before value being formatted)


Size {h|l}Meaning
hForce short integer
lForce long integer


TypeMeaning
d, iSigned decimal integer
uUnsigned decimal integer
oOctal integer (this option is non-ANSI, i.e. TI specific)
bBinary integer (this option is non-ANSI, i.e. TI specific)
xLowercase hexadecimal integer
XUppercase hexadecimal integer
eFloating point, format [-]d.dddde[sign]ddd (exponential format)
ELike 'e' but with uppercase letter for the exponent
f floating point, format [-]dddd.dddd
gFloating point: most compact float format available ('e' or 'f'); this is the most common option, used for most dialog floats
GLike 'g' but with uppercase letter for the exponent
rFloating point, engineering form (this option is non-ANSI, i.e. TI specific)
RLike 'r' but with uppercase letter for the exponent
yFloating point, mode specified float format (this option is non-ANSI, i.e. TI specific)
YLike 'y' but with uppercase letter for the exponent
cCharacter
sString
pPointer (0xhhhhhhhh); principally the same as '#.8x'
%None: the character '%' is printed instead

sprintf returns the number of bytes output, not including the terminating null byte in the count.

char *strcpy (char *dest, const char *src);

Copies string src to dest.

strcpy copies string src to dest, stopping after the terminating null character has been moved. Returns dest.

NOTE: If the objects pointed to by src and dest overlap in memory, the behavior is undefined. strcpy assumes that src points to a buffer large enough to hold dest.

char *strncpy (char *dest, const char *src, unsigned long maxlen);

Copies at most maxlen characters of src to dest.

strncpy copies up to maxlen characters from src into dest, truncating or null-padding dest. The target string, dest, might not be null-terminated if the length of src is maxlen or more. Returns dest.

NOTE: If the objects pointed to by src and dest overlap in memory, the behavior is undefined. strcpy assumes that src points to a buffer large enough to hold maxlen characters.

char *strcat (char *dest, const char *src);

Appends src to dest.

strcat appends a copy of src to the end of dest, overwriting the null character terminating the string pointed to by src. The length of the resulting string is strlen(dest) + strlen(src). strcat returns a pointer to the concatenated strings (this is src in fact).

NOTE: This routine assumes that src points to a buffer large enough to hold the concatenated string.

char *strncat (char *dest, const char *src, unsigned long maxlen);

Appends at most maxlen characters of src to dest.

strncat copies at most maxlen characters of src to the end of dest and then appends a null character. The null character terminating src is overwritten by the first character in dest. The maximum length of the resulting string is strlen(dest) + maxlen. strncat returns dest.

NOTE: This routine assumes that src points to a buffer large enough to hold the concatenated string. Since strncat appends a null character to the result, it may add maxlen+1 characters to the string.

short strcmp (const char *s1, const char *s2);

Compares one string to another.

strcmp performs an unsigned comparison of s1 to s2. It starts with the first character in each string and continues with subsequent characters until the corresponding characters differ or until the end of the strings is reached. strcmp returns a value that is More precise, if the strings differ, the value of the first nonmatching character in s2 subtracted from the corresponding character in s1 is returned.

NOTE: This routine is declared as "short" although ANSI standard proposes "long". It is important, because TIOS strcmp routine does not put anything in higher half of D0 register, so its content is unpredictable!

short strncmp (const char *s1, const char *s2, unsigned long maxlen);

Compares at most maxlen characters of one string to another.

strncmp makes the same unsigned comparison as strcmp, but looks at no more than maxlen characters. It starts with the first character in each string and continues with subsequent characters until the corresponding characters differ or until it has examined maxlen characters. strncmp returns an int value based on the result of comparing s1 (or part of it) to s2 (or part of it): More precise, if the strings differ, the value of the first nonmatching character in s2 subtracted from the corresponding character in s1 is returned. The subtraction casts the input strings to unsigned chars so that the characters in the range 128..255 are considered above the characters in the range 0..127.

NOTE: This routine is declared as "short" although ANSI standard proposes "long". It is important, because TIOS strncmp routine puts a garbage in higher half of D0 register!

unsigned long strlen (const char *str);

Calculates length of a string.

strlen calculates the length of str. Returns the number of characters in str, not counting the terminating null character.

char *strchr (const char *str, short c);

Finds c in str.

strchr scans a string in the forward direction, looking for a specific character. strchr finds the first occurrence of the character c in the string str. The null-terminator is considered to be part of the string, so that, for example,
strchr (strs, 0)
returns a pointer to the terminating null character of the string strs. Returns a pointer to the first occurrence of the character c in str. If c does not occur in str, strchr returns NULL.

unsigned long strcspn (const char *s1, const char *s2);

Scans a string.

strcspn returns the length of the initial segment of string s1 that consists entirely of characters not from string s2. If string s1 contains no characters from string s2, strcspn returns the length of string s1.

char *strpbrk (const char *s1, const char *s2);

Scans one string for the first occurrence of any character that's in a second string.

strpbrk scans a string, s1, for the first occurrence of any character appearing in s2. strpbrk returns a pointer to the first occurrence of any of the characters in s2. If none of the s2 characters occurs in s1, it returns NULL.

char *strrchr (const char *str, short c);

Finds the last occurrence of c in str.

strrchr scans a string in the reverse direction, looking for a specific character. strrchr finds the last occurrence of the character c in the string str. The null-terminator is considered to be part of the string. strrchr returns a pointer to the last occurrence of the character c. If c does not occur in str, strrchr returns NULL.

unsigned long strspn (const char *s1, const char *s2);

Scans a string for a segment that is a subset of a set of characters.

strspn finds the initial segment of string s1 that consists entirely of characters from string s2. Returns the length of the initial segment of s1 that consists of characters entirely from s2. If s1 contains no characters from s2, NULL is returned.

char *strstr (const char *s1, const char *s2);

Finds the first occurrence of a substring in another string.

strstr scans s1 for the first occurrence of the substring s2. strstr returns a pointer to the element in s1, where s2 begins (points to s2 in s1). If s2 does not occur in s1, strstr returns NULL.

char *strtok (char *s1, const char *s2);

Scans s1 for the first token not contained in s2.

strtok considers the string s1 to consist of a sequence of zero or more text tokens, separated by spans of one or more characters from the separator string s2. The first call to strtok returns a pointer to the first character of the first token in s1 and writes a null character into s1 immediately following the returned token. Subsequent calls with NULL for the first argument will work through the string s1 in this way, until no tokens remain. The separator string, s2, can be different from call to call. strtok returns a pointer to the token found in s1. A null pointer is returned when there are no more tokens.

char *strerror (short err_no);

Gives an error message string.

strerror returns a pointer to string which contains text of the system error message err_no. Note that this is not a TI-Basic error message, but a low level error message. Here is a complete table of such messages:

0no error
1no such file entry
2I/O error
3not a serial device
4out of memory
5permission denied
6block device required
7no such device
8invalid argument
9file table is full
10device directory is full
11no space left on device
12no more allocation blocks
13no more data blocks on device
14file is open
15no RAM space configured
16no heap space configured
17seek can't extend read only file
18bad file descriptor - file not open
19invalid signal number
20argument out of range
21result out of range

Other values of err_no will generate "undefined errno value" message.

NOTE: Previous releases of TIGCCLIB prior to 2.0 reports wrongly that err_no is a TI-Basic error code, which is not true. To get a pointer to TI-Basic error message, use find_error_message function.

void *memcpy (void *dest, const void *src, unsigned long len);

Copies a block of len bytes from src to dest.

memcpy copies a block of len bytes from src to dest. If src and dest overlap, the memcpy is ill-behaved (in such case, use memmove instead). memcpy returns dest.

void *memchr (const void *str, short c, unsigned long len);

Searches the first len bytes of array str for character c.

memchr searches the first len bytes of the block pointed to by str for character c. On success, memchr returns a pointer to the first occurrence of c in str. Otherwise, it returns NULL.

void *memmove (void *dest, const void *src, unsigned long len);

Copies a block of len bytes from src to dest, with possibility of overlaping of source and destination block.

memmove copies a block of len bytes from src to dest. Even when the source and destination blocks overlap, bytes in the overlapping locations are copied correctly (in opposite to memcpy). memmove returns dest.

short memcmp (const void *s1, const void *s2, unsigned long len);

Compares two blocks, s1 and s2, for a length of exactly len bytes.

memcmp compares the first len bytes of the blocks s1 and s2 as unsigned chars. Since it compares bytes as unsigned chars, memcmp returns a value For example, memcmp("\xFF","\x7F",1) returns a value greater than 0. More precise, the exact return value is the result of subtracting the first pair of values that differ in the two blocks being compared based on them being signed chars.

NOTE: This routine is declared as "short" although ANSI standard proposes "long". It is important, because TIOS memcmp routine puts a garbage in higher half of D0 register!

void *memset (void *buffer, short c, unsigned long num);

Sets num bytes of buffer to byte c.

memset sets the first num bytes of the array buffer to the character c. memset is faster than _memset, because it sets a memory in a 4-byte chunks as long as possible. memset returns buffer.

void *_memset (void *buffer, short c, unsigned long num);

Sets num bytes of buffer to byte c.

_memset is a slower (byte-by-byte) variant of memset.


Constants and predefined types


type size_t

size_t is a type proposed in ANSI C for defining size of strings and memory blocks. It is defined here as
typedef unsigned long size_t;

const NULL

NULL is a null-pointer value, defined as (void *) 0.

Return to the main index