Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.
We recommend using Visual Studio 2017

strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

 

The latest version of this topic can be found at strncmp, wcsncmp, _mbsncmp, _mbsncmp_l.

Compares up to the specified count of characters of two strings.

System_CAPS_ICON_important.jpg Important

_mbsncmp and _mbsncmp_l cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

int strncmp(  
   const char *string1,  
   const char *string2,  
   size_t count   
);  
int wcsncmp(  
   const wchar_t *string1,  
   const wchar_t *string2,  
   size_t count   
);  
int _mbsncmp(  
   const unsigned char *string1,  
   const unsigned char *string2,  
   size_t count   
);  
int _mbsncmp_l(  
   const unsigned char *string1,  
   const unsigned char *string2,  
   size_t count,   
   _locale_t locale  
);int _mbsnbcmp(  
   const unsigned char *string1,  
   const unsigned char *string2,  
   size_t count   
);  

Parameters

string1, string2
Strings to compare.

count
Number of characters to compare.

locale
Locale to use.

The return value indicates the relation of the substrings of string1 and string2 as follows.

Return valueDescription
< 0string1 substring less than string2 substring
0string1 substring identical to string2 substring
> 0string1 substring greater than string2 substring

On a parameter validation error, _mbsncmp and _mbsncmp_l return _NLSCMPERROR, which is defined in <string.h> and <mbstring.h>.

The strncmp function performs an ordinal comparison of at most the first count characters in string1 and string2 and returns a value indicating the relationship between the substrings. strncmp is a case-sensitive version of _strnicmp. wcsncmp and _mbsncmp are case-sensitive versions of _wcsnicmp and _mbsnicmp.

wcsncmp and _mbsncmp are wide-character and multibyte-character versions of strncmp. The arguments of wcsncmp are wide-character strings; those of _mbsncmp are multibyte-character strings. _mbsncmp recognizes multibyte-character sequences according to a multibyte code page and returns _NLSCMPERROR on an error.

Also, _mbsncmp and _mbsncmp_l validate parameters. If string1 or string2 is a null pointer, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, _mbsncmp and _mbsncmp_l return _NLSCMPERROR and set errno to EINVAL. strncmp and wcsncmp do not validate their parameters. These functions behave identically otherwise.

The comparison behavior of _mbsncmp and _mbsncmp_l is affected by the setting of the LC_CTYPE category setting of the locale. This controls detection of leading and trailing bytes of multibyte characters. For more information, see setlocale. The _mbsncmp function uses the current locale for this locale-dependent behavior. The _mbsncmp_l function is identical except that it uses the locale parameter instead. For more information, see Locale. If the locale is a single-byte locale, the behavior of these functions is identical to strncmp.

Generic-Text Routine Mappings

TCHAR.H routine_UNICODE & _MBCS not defined_MBCS defined_UNICODE defined
_tcsnccmpstrncmp_mbsncmpwcsncmp
_tcsncmpstrncmp_mbsnbcmpwcsncmp
_tccmpMaps to macro or inline function_mbsncmpMaps to macro or inline function
not applicablenot applicable_mbsncmp_lnot applicable
RoutineRequired header
strncmp<string.h>
wcsncmp<string.h> or <wchar.h>
_mbsncmp, _mbsncmp_l<mbstring.h>

For additional compatibility information, see Compatibility.

// crt_strncmp.c  
#include <string.h>  
#include <stdio.h>  
  
char string1[] = "The quick brown dog jumps over the lazy fox";  
char string2[] = "The QUICK brown fox jumps over the lazy dog";  
  
int main( void )  
{  
   char tmp[20];  
   int result;  
   printf( "Compare strings:\n      %s\n      %s\n\n",  
           string1, string2 );  
   printf( "Function:   strncmp (first 10 characters only)\n" );  
   result = strncmp( string1, string2 , 10 );  
   if( result > 0 )  
      strcpy_s( tmp, sizeof(tmp), "greater than" );  
   else if( result < 0 )  
      strcpy_s( tmp, sizeof(tmp), "less than" );  
   else  
      strcpy_s( tmp, sizeof(tmp), "equal to" );  
   printf( "Result:      String 1 is %s string 2\n\n", tmp );  
   printf( "Function:   strnicmp _strnicmp (first 10 characters only)\n" );  
   result = _strnicmp( string1, string2, 10 );  
   if( result > 0 )  
      strcpy_s( tmp, sizeof(tmp), "greater than" );  
   else if( result < 0 )  
      strcpy_s( tmp, sizeof(tmp), "less than" );  
   else  
      strcpy_s( tmp, sizeof(tmp), "equal to" );  
   printf( "Result:      String 1 is %s string 2\n", tmp );  
}  

Compare strings:  
      The quick brown dog jumps over the lazy fox  
      The QUICK brown fox jumps over the lazy dog  
  
Function:   strncmp (first 10 characters only)  
Result:      String 1 is greater than string 2  
  
Function:   strnicmp _strnicmp (first 10 characters only)  
Result:      String 1 is equal to string 2  

System::String::Compare

String Manipulation
Locale
Interpretation of Multibyte-Character Sequences
_mbsnbcmp, _mbsnbcmp_l
_mbsnbicmp, _mbsnbicmp_l
strcmp, wcscmp, _mbscmp
strcoll Functions
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l

Show: