digitalmars.com                      
Last update Sun Mar 4 12:00:59 2018

string.h

memchr, _fmemchr

Header
string.h
memory.h
Prototype
void *memchr(const void *buf1, int c, size_t count);
void __far *__far _fmemchr(const void __far *buf1, int c, size_t count);
Description
memchr searches in the buffer, buf, for a byte with the value of c. The search continues for count bytes or until a value of c is encountered. _fmemchr is a model-independent (large-model) form of the memchr function.
Synonym
Function: fmemchr
Return Value
memchr and _fmemchr return a pointer (or a far pointer) to the first location of c in buf. Otherwise, these functions return NULL.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
memcpy memcmp memset strcmp strcat _strset strrchr
Example
/* Example for memchr */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

char test[] = "Test String";

void main()
{
 char search = 'S', *result;

 printf("The test string is \"% s\"\n", test);
 printf("memchr() looking for 'S'\n");
 result = memchr(test, search, 12);
 if (result != NULL)
   printf("Character 'S' found at (% d)\n",
           result -test + 1);
 else
   printf("Character 'S' was not found in
           search string\n");
}
Output
The test string is "Test String"
memchr() looking for 'S'
Character 'S' found at (6)

memcmp, _fmemcmp

Header
string.h
memory.h
Prototype
int memcmp(const void *buf1, const void *buf2, size_t count); int __far _fmemcmp(const void __far *buf1, const void __far *buf2, size_t count);
Description
memcmp compares each successive byte pointed to by pointer buf1 with the corresponding byte pointed to by buf2 until they do not have the same value or until the number of bytes specified in count have been compared. memcmp returns an integer less than, equal to, or greater than zero, depending on whether the last byte compared in the buffer pointed to by buf1 is less than, equal to, or greater than the corresponding byte pointed to by buf2.

_fmemcmp is a model-independent (large-model) form of the memcmp function.

Synonym
Function: fmemcmp
Return Value
Both functions return the following types of values: less than 0 (if buf1 is less than buf2), 0 (if buf1 equals buf2), or greater than 0 (if buf1 is greater than buf2.)
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
memset _memicmp memchr strcat strrchr strcmp
Example
/* Example for memcmp */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char test1[] = "This is test string 1";
char test2[] = "This is test string 2";

void main()
{
 int result;

 printf("Test string 1 is \"% s\"\n", test1);
 printf("Test string 2 is \"% s\"\n", test2);

 printf("\nComparing 1 and 2 for 20 bytes\n");
 result = memcmp(test1, test2, 20);
 if (!result)
    printf("1 and 2 are");
 else
    printf("1 and 2 are not");
 printf("the same for 20 bytes\n");

 printf("\nComparing 1 and 2 for 21 bytes\n");
 result = memcmp(test1, test2, 21);
 if (!result)
    printf("1 and 2 are");
 else
    printf("1 and 2 are not");
 printf("the same for 21 bytes\n");
}
Output
Test string 1 is "This is test string 1"
Test string 2 is "This is test string 2"

Comparing 1 and 2 for 20 bytes
1 and 2 are the same for 20 bytes

Comparing 1 and 2 for 21 bytes
1 and 2 are not the same for 21 bytes

_memccpy, _fmemccpy

Header
string.h
memory.h
Prototype
void *_memccpy(void *dest, void *src, int c, unsigned int count);
void __far *__far _fmemccpy(void __far *dest, void __far *src, int c, unsigned int count);
Description
These functions copy a block of memory from src to dest. The copy operation stops when either the character c has been copied, or count bytes have been copied.

The _fmemccpy function is a model-independent (large-model) form of the _memccpy y function.

Synonym
Functions: memccpy, fmemccpy
Return Value
If the character c is copied, these functions return a pointer to the byte in dest immediately following the byte that contains c. If c is not copied, these functions return NULL.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
memchr memcpy memset
Example
/* Example of _memccpy */

#include <stdio.h>
#include <string.h>

char string[60] =
 "Now is the time for all good men";

void main()
{
 char buf[61];
 char *dest;

 dest = _memccpy(buf, string, 'l', 60);
 if (dest != NULL)
    *dest = '\0';

 printf("Should have copied to the first
         \"l\" or until the end, ");
 printf("which evercame first.
         Result is:\n% s\n", buf);
}
Output
Should have copied to the first "l" or until the end, which evercame first. Result is:

Now is the time for al

memcpy, _fmemcpy

Header
string.h
memory.h
Prototype
void *memcpy(void *buf1, const void *buf2, size_t count);
void __far *__far _fmemcpy(void __far *buf1, const void __far *buf2, size_t count);
Description
memcpy copies the number of characters specified in count from buf2 to buf1. buf1 is returned. Although memcpy is faster than memmove, memcpy does not ensure that the source bytes in the overlapping region are copied before being overwritten. In this situation, use memmove.
Synonym
Function: fmemcpy
Return Value
Both functions return buf1.
Compatibility
DOS, Windows 3. x, Phar Lap/ DOSX, Win32
See Also
memcmp memset memcmp memmove strcmp strcat _strset strrchr
Example
/* Example for memcpy */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char test1[] = "Sample String.";
char test2[15];

void main()
{
 printf("Copying test1 to test2\n");
 memcpy(test2, test1, 15);
 printf("Result is \"% s\"\n", test2);
}
Output
Copying test1 to test2
Result is "Sample String."

_memicmp, _fmemicmp

Header
string.h
memory.h
Prototype
int _memicmp(const void *buf1, const void *buf2, size_t count);
int __far _fmemicmp(const void __far *buf1, const void __far *buf2, size_t count);
Description
These functions compare the first count characters from buf1 with those in buf2 on a byte for byte basis, without reference to the case of the letters being compared. Uppercase and lowercase letters are considered to be equivalent. All uppercase (capital) letters in both buf1 and buf2 are converted to lowercase before the comparison is done. This function is identical to memcmp except it ignores case.

Function _fmemicmp is a model-independent (large-model) form of the _memicmp function.

Synonym
Function: fmemicmp
Return Value
These functions return an integer value which depends on the relationship of buf1 to buf2, as follows:

Returns a value if
< 0 buf1 less than buf2
= 0 buf1 identical to buf2
> 0 buf1 greater than buf2
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
memchr memcpy memcmp memset
Example
/* Example of _memicmp */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char test1[] = "this is test string 1";
char test2[] = "THIS IS TEST STRING 2";

void main()
{
 int result;

 printf("Test string 1 is \"% s\"\n", test1);
 printf("Test string 2 is \"% s\"\n", test2);

 printf("\nComparing 1 and 2 for 20 bytes\n");
 result = _memicmp(test1, test2, 20);
 if (!result)
    printf("1 and 2 are");
 else
    printf("1 and 2 are not");

 printf("the same for 20 bytes\n");
 printf("\nComparing 1 and 2 for 21 bytes\n");
 result = _memicmp(test1, test2, 21);
 if (!result)
    printf("1 and 2 are");
 else
    printf("1 and 2 are not");
 printf(" the same for 21 bytes\n");
}
Output
Test string 1 is "this is test string 1"
Test string 2 is "THIS IS TEST STRING 2"

Comparing 1 and 2 for 20 bytes
1 and 2 are the same for 20 bytes

Comparing 1 and 2 for 21 bytes
1 and 2 are not the same for 21 bytes

memmove, _fmemmove

Header
string.h
Prototype
void *memmove(void *buf1, const void *buf2, size_t count);
void __far *__far _fmemmove(void __far *buf1, const void __far *buf2, size_t count);
Description
memmove copies the number of characters specified in count from buf2 to buf1. memmove, slower than memcpy, can handle overlapping moves.

_fmemmove is a model-independent (large-model) form memmove.

Synonym
Function: fmemmove
Return Value
buf1 is returned.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
memcpy
Example
/* Example for memmove */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char test1[] = "Sample String.";
char test2[15];

void main()
{
 printf("Copying test1 to test2\n");
 memmove(test2, test1, 15);
 printf("Result is \"% s\"\n",test2);
}
Output
Copying test1 to test2

Result is "Sample String."

memset, _fmemset, setmem

Header
string.h
memory.h
Prototype
void *memset(void *buf, int val, size_t count);
void __far *__far _fmemset(void __far *buf, int val, size_t count);
void setmem(void *buf, size_t count, int val);
Description
memset sets the first count characters pointed to by buf to the value specified by val. It returns buf. Function_fmemset is a model-independent (large-model) form memset. setmem is just a macro for memset, reversing the second and third parameters.
Synonym
Function: fmemset
Return Value
Both functions return buf.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
strcat _strset strrchr strcmp
Example
/* Example for memset */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char buffer[20];

void main()
{
 printf("buffer before memset: \"% s\"\n",
        buffer);
 memset(buffer, 'x', 6);
 printf("buffer after memset: \"% s\"\n",
        buffer);
}
Output
buffer before memset:
"" buffer after memset: "xxxxxx"

_movedata

Header
string.h
Prototype
void _movedata(unsigned srcseg, unsigned srcoff, unsigned dstseg, unsigned dstoff, size_t numbytes);
Description
The _movedata function moves numbytes bytes from the source address specified by segment srcseg and offsets srcoff to the destination address specified by segment dstseg and offset dstoff.

Use _movedata to move data between segments. For normal intra-segment movement of data, use memcpy or memmove instead. _movedata does not handle overlapping moves correctly.

Synonym
Function: movedata
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_FP Functions
memcpy memmove
Example
/* Example of _movedat */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <dos.h>

void main()
{
 char __far *src = "this is a test";
 char __far *dest;

 if ((dest = malloc (80)) != NULL)
 {
   _movedata(_FP_SEG(src), _FP_OFF(src),
             _FP_SEG(dest), _FP_OFF(dest),
   strlen(src) + 1);
   printf("The source is %p and contains
           \"% s\"\n", src, src);
   printf("The destination is %p and contains
           \"% s\"\n", dest, dest);
   free(dest);
 }
}
Output
The source is 207B: 0042 and contains "this is a test"
The destination is 307C: 01CA and contains "this is a test"

movmem

Header
memory.h
Prototype
void movmem(const void *src, void *dest, size_t length);
Description
The movmem function moves a block of data from src to dest. The length argument indicates the number of bytes to copy. This function moves the data correctly, even if the blocks overlap.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_movedata
Example
/* Example for movmem */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mem.h>

void main()
{
 char *src = "This is a test";
 char *dest;
 int len;

 len = strlen(src) + 1;
 dest = malloc(len);
 movmem(src, dest, len);
 printf("The source string is \"% s\".\nThe
         destination string is \"% s\"\n",
         src, dest);
}
Output
The source string is "This is a test".

The destination string is "This is a test"

_strdup, _fstrdup

Header
string.h
Prototype
char *_strdup(const char *string);
char __far *__far _fstrdup(
const char __far *string);
Description
The _strdup and _fstrdup functions allocate memory with a call to malloc, copy the string into this memory, and return a pointer to the memory containing the string. The functions return NULL if memory cannot be allocated.

The _fstrdup function provides additional control over the heap used for string duplication. The function returns a far pointer to a copy of the string allocated from the far heap.

Synonym
Functions: strdup, fstrdup
Return Value
All functions return a pointer to the allocated memory containing the string. NULL is returned if memory cannot be allocated.
Compatibility
strdup: DOS Windows 3.x Phar Lap/ DOSX Win32
_fstrdup: DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of _strdup */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void main()
{
 char *str1 = "This is a test string";
 char *str2;

 printf("The original string: \"% s\"\n", str1);
 str2 = _strdup(str1);
 printf("The string from _strdup(): \"% s\"\n", str2);
}
Output
The original string: "This is a test string"
The string from _strdup(): "This is a test string"

_stricmp, _fstricmp

Header
string.h
Prototype
int _stricmp(const char *string1, const char *string2);
int __far _fstricmp(const char __far *string1, const char __far *string2);
Description
The _stricmp function compares the lowercase versions of the strings specified in string1 and string 2. The comparison begins with the first character of each string and continues until corresponding characters differ or until the ends of the strings are reached.

The _fstricmp function is a model-independent (large model) form of _stricmp. The functions are identical, except that the _fstricmp arguments are far pointers.

Synonym
Function: stricmp, fstricmp
Return Value
Returns... if...
< 0 string1 is less than string2
= 0 string1 is equal to string2
> 0 string1 is greater than string2
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
strcat strcpy strncat strncmp strncpy strncmpi strncmpl _strnicmp
Example
See strcmp

_strlwr, _fstrlwr

Header
string.h
Prototype
char *_strlwr(char *string);
char __far *__far _fstrlwr(char __far *string);
Description
The _strlwr function converts upper case characters in the string argument to lower case.

The _fstrlwr function is a model-independent (large model) form of _strlwr. They are identical, except that the _fstrlwr argument and return values are far pointers.

Synonym
Function: strlwr, fstrlwr
Return Value
Return a pointer to the converted string.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of _strlwr */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "Mixed Case String";

 printf("The original string: \"% s\"\n",
        str);
 _strlwr (str);
 printf("The string after _strlwr:
         \"% s\"\n", str);
}
Output
The original string: "Mixed Case String"

The string after _strlwr: "mixed case string"

strncmpi, strncmpl, _strnicmp, _fstrnicmp

Header
string.h
Prototype
int strncmpi(const char *str1, const char *str2, size_t n);
int strncmpl(char *str1, char *str2, int n);
int _strnicmp(const char *str1, const char *str2, size_t n);
int __far _fstrnicmp(const char __far *str1, const char __far *str2, size_t n);
Description
These functions are case-insensitive versions of strncmp. The first n characters of each string are compared. If either is less than n characters long, the comparison terminates; the return value is the result of the comparison up until the termination. The returned value is zero for a successful match; a positive or negative number represents the difference in the mismatched characters.

The _fstrnicmp function is a model-independent (large model) form of _strnicmp. They are identical, except that the _fstrnicmp arguments and return values are far.

Synonym
Function: strnicmp
Return Value
Returns if
< 0 string1 is less than string2
= 0 string1 is equal to string2
> 0 string1 is greater than string2
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
strncmp strcmp

_strnset _fstrnset

Header
string.h
Prototype
char *_strnset(char *string, int ch, size_t n);
char __far *__far _fstrnset(char __far *string, int ch, size_t n);
Description
These functions set, at most, n characters of string to ch (converted to char) and return a pointer to the altered string. If n is greater than the length of string, the length of string is used in place of n. The _fstrnset function is a model-independent (large model) form of _strnset. They are identical, except that the _fstrnset arguments and return values are far.
Synonym
Functions: strnset, fstrnset
Return Value
These functions return a pointer to a string.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
See Also
_strset
Example
/* Example for _strnset */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void main()
{
 char *str = "_strnset Example string";

 printf("This is the string: \"% s\"\n", str);
 printf("After _strnset(str, 'x', 10):
         \"% s\"\n", _strnset(str, 'x', 10));
 printf("After _strnset(str, 'x', 100):
         \"% s\"\n", _strnset(str, 'x', 100));
}
Output
This is the string: "_strnset Example string"
After _strnset(str, 'x', 10)
: "xxxxxxxxxxxample string" After _strnset(str, 'x', 100): "xxxxxxxxxxxxxxxxxxxxxxx"

_strrev, _fstrrev

Header
string.h
Prototype
char *_strrev(char *string);
char __far *__far _fstrrev(char __far* string);
Description
These functions reverse the order of characters in string, leaving a terminating '\0' at the end.

The _fstrrev function is a model-independent (large model) form of strrev. These functions are identical, except that the _fstrrev argument and return value are far pointers.

Synonym
Function: strrev, fstrrev
Return Value
Both functions return a pointer to the altered string.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example for _strrev */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void main()
{
 char str[80];

 printf("Enter a string: ");
 gets(str);

 printf("\nThe results of _strrev are:\n
\"% s\"\n", _strrev(str));
}
Output
Enter a string: So much time, so little to do

The results of _strrev are:
"od ot elttil os ,emit hcum oS"

_strset, _fstrset

Header
string.h
Prototype
char *_strset(char *string, int ch);
char __far *__far _fstrset(char __far *string, int ch);
Description
These functions set all the characters in string to ch except the terminating null character.

The _fstrset function is a model-independent (large model) form of _strset. These functions are identical, except that the _fstrset pointer arguments and return value are far pointers.

Synonym
Function: strset, fstrset
Return Value
These functions return a pointer to the altered string.
Compatibility
_strset: DOS Windows 3.x Phar Lap/ DOSX Win32 _fstrset: DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example for _strset */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void main()
{
 char *str = "_strset Example string";

 printf("This is the string: \"% s\"\n", str);
 printf("After _strset(str, 'x'): \"% s\"\n",
        _strset(str, 'x'));
}
Output
This is the string: "_strset Example string"
After _strset(str, 'x'): "xxxxxxxxxxxxxxxxxxxxxx"

_strtime

Header
time.h
Prototype
char *_strtime(char *timestr);
Description
The _strtime function copies the current time to the buffer pointed to by the timestr argument.

The time string has the following format:

hh:mm:ss

where hh represents the hour in 24-hour notation, mm represents the minutes past the hour, and ss represents the seconds.

The buffer must be at least 9 bytes long.

Return Value
A pointer to the text string.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime ctime localtime
Example
See _strdate

_strupr, _fstrupr

Header
string.h
Prototype
char *_strupr(char *string);
char __far *__far _fstrupr(char *string);
Description
These functions convert lowercase characters in string to uppercase.

The _fstrupr function is a model-independent (large model) form of _strupr. They are identical, except that the _fstrupr argument and the return value are far pointers.

Synonym
Functions: strupr, fstrupr
Return Value
Returns string.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
See Also
_strlwr _tolower
_toupper
Example
/* Example of _strupr */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "Mixed Case String";

 printf("The original string: \"% s\"\n", str);
 _strupr(str);
 printf("The string after _strupr:
         \"% s\"\n", str);
}
Output
The original string: "Mixed Case String"
The string after _strupr: "MIXED CASE STRING"

_swab

Header
stdlib.h
Prototype
void _swab(char *source, char *destination, int n);
Description
The _swab function copies n bytes from source, swapping each pair of adjacent bytes. destination stores the converted string. The integer n should be even as pairs of characters are swapped.
Synonym
Function: swab
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for _swab */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
void main()
{
 char str[80];
 char dst[80];
 int len;

 printf("Enter a string: ");
 gets(str);
 strcpy(dst, str);

 len = strlen(str);
 len -= len % 2;

 _swab(str, dst, len);

 printf("\nThe results of _swab are:\n
         \"% s\"\n", dst);
}
Output
Enter a string: It's a Push-me-pull-you

The results of _swab are:
"tIs'a P su-hemp-lu-loyu"

stpcpy

Header
string.h
Prototype
char *stpcpy(char *s1, const char *s2);
Description
The stpcpy function copies the string pointed to by s2 into the buffer pointed to by s1. It is similar to the normal library strcpy function except that it returns a pointer to the end of the copied string. This is useful when concatenating strings.
Return Value
A pointer to the end of the copied string.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
strcpy
Example
/* Example for stpcpy */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void main()
{
  char s1[8], *s2 = "Eu", *s3 = "re",
              *s4 = "ka";

  stpcpy(stpcpy(stpcpy(stpcpy(s1, s2),
         s3), s4), "!");
  printf("This is the string from stpcpy
          \"% s\"\n", s1);
}
Output
This is the string from stpcopy "Eureka!"

strcat, _fstrcat

Header
string.h
Prototype
char *strcat(char *string1, const char *string2);
char __far *__far _fstrcat(char __far *string1, const char __far *string2);
Description
The strcat function appends a copy of string2 onto the end of string1 and terminates the resulting string with a null character. The application code is responsible for ensuring that there is enough space in the string to hold the result.

The _fstrcat function is a model-independent (large model) form of strcat. These functions are identical, except that the _fstrcat arguments and return values are far pointers.

Synonym
Function: fstrcat
Return Value
Both functions return a pointer to string1.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of strcat */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char str1[50] = "This is string 1...";
 char str2[50] = "And this is string 2.";

 printf("String 1: \"% s\"\nString 2:
         \"% s\"\n", str1, str2);
 printf("Result of strcat: \"% s\"\n",
         strcat(str1, str2));
}
Output
String 1: "This is string 1..."
String 2: "And this is string 2."
Result of strcat: "This is string 1... And this is string 2."

strchr, _fstrchr

Header
string.h
Prototype
char *strchr(const char *string, int ch);
char __far *__far _fstrchr(const char __far *string, int ch);
Description
The strchr function finds the first occurrence of the character ch in string and returns a pointer to this character. strchr is identical to the function index (which is no longer in this library).

The _fstrchr function is a model-independent (large model) form of strchr. These functions are identical, except that the _fstrchr arguments and return values are far.

Synonym
Function: fstrchr
Return Value
Pointer to character ch. A NULL pointer is returned if not found.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
See Also
memchr
Example
/* Example of strchr */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "string example";
 char *res;

 printf("Looking for 'x' in
         string \"% s\"\n", str);
 res = strchr(str, 'x');
 if (!res)
    printf("'x' was not found in
            the search string\n");
 else
    printf("'x' was found in the search
            string at offset %d\n",
            res -str);
}
Output
Looking for 'x' in string "string example"

'x' was found in the search string at offset 8

strcmp

Header
string.h
Prototype
int strcmp(const char *string1, const char *string2);
int __far _fstrcmp(const char __far *string1, const char __far *string2);
int _strcmpi(const char *string1, const char *string2);
int strcmpl(const char *string1, const char *string2);
int __far _fstrcmpl(const char __far *string1, const char __far *string2);
Description
strcmp, _strcmpi, and strcmpl compare two strings, character by character. strcmp is case sensitive whereas strcmpi and strcmpl are not.

The _fstrcmp and _fstrcmpl functions are model-independent (large model) form of strcmp and strcmpl. These functions are identical, except that the _fstrcmp and _fstrcmpl arguments are far pointers.

Synonym
Functions: fstrcmp, strcmpi
Return Value
Return if
<0 stiring1 is less than string2
=0 string1 is equal to string2
>0 string1 greater than string2
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
memcmp
Example
/* Example of strcmp, _stricmp */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char test1[] = "this is a test string";
char test2[] = "THIS IS A TEST STRING";

void main()
{
 int result;

 printf("Test string 1 is \"% s\"\n", test1);
 printf("Test string 2 is \"% s\"\n", test2);

 printf("\nComparing 1 and 2 using strcmp\n");
 result = strcmp(test1, test2);
 if (!result)
    printf("string 1 is equal to string 2\n");
 else if (result < 0)
    printf("string 1 is less than
            string 2\n");
 else
    printf("string 1 is greater than
            string 2\n");

 printf("\nComparing 1 and 2 using
         _stricmp\n");
 result = _stricmp(test1, test2);
 if (!result)
    printf("string 1 is equal to string 2\n");
 else if (result < 0)
    printf("string 1 is less than string 2\n");
 else
    printf("string 1 is greater than
            string 2\n");
}
Output
Test string 1 is "this is a test string"
Test string 2 is "THIS IS A TEST STRING"

Comparing 1 and 2 using strcmp
string 1 is greater than string 2

Comparing 1 and 2 using _stricmp
string 1 is equal to string 2

strcoll

Header
string.h
Prototype
int strcoll(const char *string1, const char *string2);
Description
The strcoll function compares the two strings specified in the string1 and string2 arguments, using the collating sequence specified by the setlocale function. Then, the function returns a value indicating the relationship between the strings.
Return Value
The following values are returned:

Returns a value if
< 0 string1 is less than string2
= 0 string1 is equal to string2
> 0 string1 is greater than string2
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
setlocale strcmp

strcpy, _fstrcpy

Header
string.h
Prototype
char *strcpy(char *string1, const char *string2);
char __far *__far _fstrcpy(char __far *string1, const __far char *string2);
Description
strcpy copies string2, including the terminating null character, into the object pointed to by string1. The _fstrcpy function is a model-independent (large model) form of strcpy.
Synonym
Function: fstrcpy
Return Value
Returns the new string pointed to by string1.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
See Also
stpcpy
Example
/* Example of strcpy */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char str1[50] = "This is the first string";
 char str2[50] = "This is the second string";

 printf("str1 = \"% s\"\n", str1);
 printf("str2 = \"% s\"\n", str2);

 strcpy(str1, str2);
 printf("\nAfter strcpy(str1, str2)...\n\n");

 printf("str1 = \"% s\"\n", str1);
 printf("str2 = \"% s\"\n", str2);
}
Output
str1 = "This is the first string"
str2 = "This is the second string"

After strcpy(str1, str2)...

str1 = "This is the second string"
str2 = "This is the second string"

strcspn, _fstrcspn

Header
string.h
Prototype
size_t strcspn(const char *string1, const char string2);
size_t __far _fstrscpn(const char __far *string1, const char __far *string2);
Description
strcspn searches string1 for the first occurrence of a character belonging to the set of characters in string2 and returns the index of this character. This value is equivalent to the length of the initial substring of string1 consisting entirely of charcters not in string2.

The _fstrcspn function is a model-independent (large model) form of strcspn. These functions are identical, except that the _fstrcspn arguments and return values are far.

Synonym
Function: fstrcspn
Return Value
Both functions return the length of the initial segment of string1 that consists of characters not found in string2. If string1 begins with a character from string2, strcspn returns 0. If no character in string2 appears in string1, then the total length of string1, not counting the null character terminator, is returned.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
Example
/* Example of strcspn */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "The quick brown fox jumped
              over the lazy dog";
 char srch[80];
 unsigned res;

 printf("The search string is:
         \n \"% s\"\n\n", str);
 printf("Enter the set of characters
         for strcspn(): ");
 gets(srch);

 res = strcspn(str, srch);

 if (res == strlen(str))
    printf("\nSorry but none of those
            characters where found.\n");
 else
    printf("\nMatching character found
            at offset %d\n", res);
}
Output
The search string is:
   "The quick brown fox jumped over the lazy dog"

Enter the set of characters for strcspn(): qzy

Matching character found at offset 4

strerror

Header
string.h
Prototype
char *strerror(int errornum);
Description
The strerror function gets a system error message asociated with an error number. It maps errornum to an error message string and returns a pointer to that string.

strerror does not print the error message. To print the message returned to stderr, use a print statement such as fprintf: 

if ((_access("datafile", 2 )) == -1)
   fprintf(stderr, _strerror(NULL));
Return Value
Returns a pointer to the error message string.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_strerror clearerr ferror perror
Example
/* Example of strerror */

#include <stdlib.h>
#include <stdio.h>
#include <io.h>
#include <string.h>
#include <fcntl.h>

void main()
{
 int f;

 f = _open("nofile. xxx", _O_RDONLY);
 if ( < 0)
    printf("Error opening file
            \" nofile. xxx\": %s\n",
            strerror(errno));
 else
 {
    printf("The file is open");
    _close (f);
 }
}
Output
Error opening file "nofile. xxx": No such file or directory

strlen, _fstrlen

Header
string.h
Prototype
size_t strlen(const char *string);
size_t __far _fstrlen(const char __far *string);
Description
The strlen function returns the length of the string in the string argument, excluding the terminating '\0'.

The _fstrlen function is a model-independent (large model) form of strlen. These functions are identical, except that the _fstrlen argument is a far pointer.

Synonym
Function: fstrlen
Return Value
Both functions return the length of the string.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of strlen */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char str[80];

 printf("Enter a string: ");
 gets(str);

 printf("There are %d characters in the
         string \"% s\"\n",
         strlen (str), str);
}
Output
Enter a string: The quick brown fox...
There are 22 characters in the string "The quick
brown fox..."

strncat, _fstrncat

Header
string.h
Prototype
char *strncat(char *string1, const char *string2, size_t n);
char __far *__far _fstrncat(char __far *string1, const char __far *string2, size_t n);
Description
This function appends the lesser of n or strlen(string2) characters of string2 onto the end of string1 and adds a terminating NULL character. It is the user's responsibility to ensure there is enough space in string1 to hold the result.

The _fstrncat function is a model-independent (large model) form of strncat. These functions are identical, except that the _fstrncat pointer arguments and return values are far pointers.

Synonym
Function: fstrncat
Return Value
Both functions return a pointer to the concatenated string.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
See Also
strcat
Example
/* Example of strncat */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char str1[25] = "This is string 1...";
 char str2[25] = "And this is string 2.";
 int len;
 len = 25 - strlen(str1);
 printf("String 1: \"% s\"\nString 2:
         \"% s\"\n",
         str1, str2);
 printf("Result of strncat(str1, str2, %d):
         \"% s\"\n",
         len, strncat(str1, str2, len));
}
Output
String 1: "This is string 1..."
String 2: "And this is string 2."
Result of strncat(str1, str2, 6): "This is
string 1... And th"

strncmp, _fstrncmp

Header
string.h
Prototype
int strncmp(const char *string1, const char *string2, size_t n);
int __far _fstrncmp(const char __far *string1, const char __far *string2, size_t n);
Description
Compares n characters of string2 to string1. The comparison stops after n characters or the end of string1. The _fstrncmp function is a model-independent (large model) form of strncmp. These functions are identical, except that the _fstrncmp arguments and return values are far.
Synonym
Function: fstrncmp
Return Value
Returns a value if
< 0 string1 is less than string2
= 0 string1 is equal to string2
> 0 string1 is greater than string2
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
strcmp
Example
/* Example of strncmp, _strnicmp */

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

char test1[] = "this is a test string XXXXX";
char test2[] = "THIS IS A TEST STRING zzzzz";

void main()
{
 int result;

 printf("Test string 1 is \"% s\"\n",
        test1);
 printf("Test string 2 is \"% s\"\n",
        test2);
 printf("\nComparing 1 and 2 using
         strncmp(str1, str2, 21)\n");
 result = strncmp(test1, test2, 21);
 if (!result)
    printf("string 1 is equal to string 2\n");
 else if (result < 0)
    printf("string 1 is less than string 2\n");
 else
    printf("string 1 is greater than string
            2\n");

 printf("\nComparing 1 and 2 using
         _strnicmp(str1, str2, 21)\n");
 result = _strnicmp(test1, test2, 21);
 if (!result)
    printf("string 1 is equal to string 2\n");
 else if (result < 0)
    printf("string 1 is less than string
            2\n");
 else
    printf("string 1 is greater than
            string 2\n");

 printf("\nComparing 1 and 2 using
         _strnicmp(str1, str2, 100)\n");
 result = _strnicmp(test1, test2, 100);
 if (!result)
    printf("string 1 is equal to string 2\n");
 else if (result < 0)
    printf("string 1 is less than string 2\n");
 else
    printf("string 1 is greater than string 2\n");
}
Output
Test string 1 is "this is a test string XXXXX"
Test string 2 is "THIS IS A TEST STRING zzzzz"

Comparing 1 and 2 using strncmp(str1, str2, 21)
string 1 is greater than string 2

Comparing 1 and 2 using _strnicmp(str1, str2, 21)
string 1 is equal to string 2

Comparing 1 and 2 using _strnicmp(str1, str2, 100)
string 1 is less than string 2

strncmpi, strncmpl, _strnicmp, _fstrnicmp

Header
string.h
Prototype
int strncmpi(const char *str1, const char *str2, size_t n);
int strncmpl(char *str1, char *str2, int n);
int _strnicmp(const char *str1, const char *str2, size_t n);
int __far _fstrnicmp(const char __far *str1, const char __far *str2, size_t n);
Description
These functions are case-insensitive versions of strncmp. The first n characters of each string are compared. If either is less than n characters long, the comparison terminates; the return value is the result of the comparison up until the termination. The returned value is zero for a successful match; a positive or negative number represents the difference in the mismatched characters.

The _fstrnicmp function is a model-independent (large model) form of _strnicmp. They are identical, except that the _fstrnicmp arguments and return values are far.

Synonym
Function: strnicmp
Return Value
Returns a value if
< 0 string1 is less than string2
= 0 string1 is equal to string2
> 0 string1 is greater than string2
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
strncmp strcmp

strncpy, _fstrncpy

Header
string.h
Prototype
char *strncpy(char *string1, const char *string2, size_t n);
char __far *__far _fstrncpy(char __far *string1, const char __far *string2, size_t n);
Description
The strncpy function copies the first n characters of string2 into string1. If string2 is longer than string1 or longer than n, the result will not be null terminated. If string2 is less than n characters, string1 will be padded to n with null characters.

The _fstrncpy function is a model-independent (large model) form of strncpy. These functions are identical, except that the _fstrncpy arguments and return values are far.

Synonym
Function: fstrncpy
Return Value
Returns string1.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
See Also
strcpy stpcpy
Example
/* Example of strncpy */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char str1[50] = "This is the first string";
 char str2[50] = "The second string is this";

 printf("str1 = \"% s\"\n", str1);
 printf("str2 = \"% s\"\n", str2);

 strncpy(str1, str2, 10);
 printf("\nAfter strncpy(str1, str2,
         10)...\n\n");

 printf("str1 = \"% s\"\n", str1);
 printf("str2 = \"% s\"\n", str2);
}
Output
str1 = "This is the first string"
str2 = "The second string is this"

After strncpy(str1, str2, 10)...

str1 = "The seconde first string"
str2 = "The second string is this"

strpbrk, _fstrpbrk

Header
string.h
Prototype
char *strpbrk(const char *string1, const char *string2);
char __far *__far _fstrpbrk(const char __far *string1, const char __far *string2);
Description
The strpbrk function finds the first occurrence in string1 of any character from string2. The terminating null character is not included in the search.

The _fstrpbrk function is a model-independent (large model) form of strpbrk. These functions are identical, except that the _fstrpbrk arguments and return values are far.

Synonym
Function: fstrpbrk
Return Value
Returns a pointer to the first occurrence in string1 of any character from string2, or NULL if no character from string2 exists in string1.
Compatibility
DOS, Windows 3.x, Phar Lap/ DOSX, Win32
Example
/* Example of strpbrk */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "The quick brown fox jumped
              over the lazy dog";
 char srch[80];
 char *res;

 printf("The search string is:\n
         \"% s\"\n\n", str);
 printf("Enter the set of characters
         for strpbrk(): ");
 gets(srch);

 res = strpbrk(str, srch);

 if (res == NULL)
   printf("\nSorry but none of those
           characters where found.\n");
 else
 {
   printf("\nMatching character found at
           offset %d\n", res -str);
   printf("The result points to
           \"% s\"\n", res);
 }
}
Output
The search sting is:
"The quick brown fox jumped over the lazy dog"

Enter the set of characters for strpbrk(): qrt

Matching character found at offset 4
The result points to "quick brown fox jumped
over the lazy dog"

strrchr, _fstrrchr

Header
string.h
Prototype
char *strrchr(const char *string, int ch);
char __far *__far _fstrrchr(const char __far *string, int ch);
Description
The strrchr function finds the last occurrence of character ch (converted to char) in string. The string's terminating null character is included in the search.

The _fstrrchr function is a model-independent (large model) form of strrchr. These functions are identical, except that the _fstrrchr arguments and return values are far pointers.

Synonym
Function: fstrrchr
Return Value
Both functions return a pointer to the last occurrence of ch in string. They return a NULL pointer if ch is not found.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of strrchr */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "Peter piper picked a peck of
pickled peppers";
 char *res;

 printf("Using strrchr to look for 'p' in string:\n \"% s\"\n\n", str);
 res = strrchr(str, 'p');
 if (!res)
    printf("'p' was not found in the search string\n");
 else
    printf("The last occurance of 'p' was found in the search string at "
      "offset %d\n", res -str);
}
Output
Using strrchr to look for 'p' in string:
"Peter piper picked a peck of pickled peppers"

The last occurance of 'p' was found in the
search string at offset 40

strspn, _fstrspn

Header
string.h
Prototype
size_t strspn(const char *string1, const char *string2);
size_t __far _fstrspn(const char __far *string1, const char __far *string2);
Description
The strspn function returns the length of the initial segment of string1 which consists entirely of characters found in string2. The null character terminating string2 is not considered in the matching process. If string1 begins with a character not in string2, strspn returns 0.

The _fstrspn function is a model-independent (large model) form of strspn. These functions are identical, except that the _fstrspn arguments are far pointers.

Synonym
Function: fstrspn
Return Value
Both functions return the length of the initial segment of string1 which consists entirely of characters found in string2.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of strspn */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "The quick brown fox jumped
              over the lazy dog";

 char srch[80];
 unsigned res;

 printf("The search string is:\n
         \"% s\"\n\n", str);
 printf("Enter the set of characters
         for strspn(): ");
 gets(srch);

 res = strspn(str, srch);

 if (res == 0)
  printf("\nSorry, but not all of those
          characters where found.\n");
 else
  printf("\nCharacters match until offset
          %d\n", res);
}
Output
The search string is:
"The quick brown fox jumped over the lazy dog"

Enter the set of characters for strspn(): ehT
kciqu z

Characters match until offset 10

strstr, _fstrstr

Header
string.h
Prototype
char *strstr(const char *string1, const char *string2);
char __far *__far _fstrstr(const char __far *string1, const char __far *string2);
Description
The strstr function returns a pointer to the first occurrence of string2 within string1.

The _fstrstr function is a model-independent (large model) form of strstr. These functions are identical, except that the _fstrstr arguments and return value are far pointers.

Synonym
Function: fstrstr
Return Value
These functions return a pointer to the first occurence of string2 within string1, or they return NULL if no occurrence was found. If string2 is of 0 length, the functions return string1.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example of strstr */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

void main()
{
 char *str = "The quick brown fox jumped

              over the lazy dog";
 char srch[80];
 char *res;

 printf("The source string is:\n
         \"% s\"\n\n", str);
 printf("Enter the search string for
         strstr(): ");
 gets(srch);

 res = strstr(str, srch);

 if (res == NULL)
   printf("\nSorry, that string was not
           found.\n");
 else
 {
   printf("\nMatching string found at offset
           %d\n", res -str);
   printf("Result points to the string:
           \n \"% s\"\n", res);
 }
}
Output
The source string is:
"The quick brown fox jumped over the lazy dog"

Enter the search string for strstr(): lazy

Matching string found at offset 36
Result points to the string:
"lazy dog"

strtok, _fstrtok

Header
string.h
Prototype
char * strtok(char * string1, const char * string2);
char __far *__far _fstrtok(char __far *string1, const char __far *string2);
Description
strtok parses string1 into tokens delimited by characters in string2. It returns a pointer to the first character in string1, which is not one of the delimiting characters, and writes a '\0' at the position of the next delimiter. Because an internal record is stored of the current position within the string, a subsequent strtok call with a NULL value for string1 continues parsing from the position reached in the previous call. string2 may change between calls.

The _fstrtok function is a model-independent (large model) form of strtok. These functions are identical, except that the _fstrtok arguments and return value are far pointers.

Synonym
Function: fstrtok
Return Value
The first time these functions are called, they return a pointer to the first token in string1. In later calls with the same token string, a pointer to the next token is returned. When there are no more tokens, a NULL pointer is returned.
Compatibility
DOS Windows 3.x Phar Lap/ DOSX Win32
Example
/* Example for strtok */

#include <stdio.hgt
#include <stdlib.h>
#include <string.h>

#define delim "\n\r\t\v "
char *gettoken(FILE *fp)
{
 static char linebuf[128];
 static char *res = NULL;

 do
 {
   if (res == NULL)
   {
     fgets(linebuf, 128, fp);
     res = strtok(linebuf, delim);
   }
   else
     res = strtok(NULL, delim);
 } while (! feof (fp) && !res);
 return res;
}
void main()
{
 char fname[_MAX_PATH];
 char *token;
 FILE *fp;

 printf("Enter filename: ");
 gets(fname);

 if ((fp = fopen(fname, "r")) == NULL)
 {
    perror("Unable to open file");
    exit(EXIT_FAILURE);
 }
 do
 {
    token = gettoken(fp);
    printf("% s\n", token);
 } while (!feof(fp));
}
Output
 Enter filename: strtok. c
 /*
 Example
 for
 strtok
 */
 #include
 <stdio.h>
 #include
 <stdlib.h>
 .
 .
 .
 =
 gettoken
 (fp);
 printf
 ("% s\n",
 token);
 }
 while
 (! feof(fp));
 }

strxfrm

Header
string.h
Prototype
size_t strxfrm(char *string1, const char *string2, size_t count);
Description
The strxfrm function transforms string2 to a differently collated form and stores it in string1. The count argument is the maximum number of characters placed in string1. The transformation uses the collating sequence for the locale, as set by the setlocale function.

The size of the array needed to hold the transformation of the source string can be expressed as:

1 + strxfrm(NULL, string, 0)

Return Value
The length of the transformed string, not counting the terminating null character. The contents of string1 are unpredictable if the return value is greater than or equal to count.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
localeconv setlocale strcmp strcoll

_sys_errlist

Header
string.h
Prototype
extern char *_sys_errlist[];
Description
This variable is an array of error messages indexed by errno values. Error messages printed by perror and returned by strerror and _strerror are retrieved from this array. It is better to use those functions rather than access the array directly because the functions handle out-of-range errno values correctly.
Synonym
Variable: sys-errlist
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
errno
_sys_nerr perror
strerror

_sys_nerr

Header
string.h
Prototype
extern int _sys_nerr;
Description
This variable tells how many elements the _sys_errlist variable contains.
Synonym
Variable: sys_nerr
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
errno
_sys_errlist
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums