strchr, wcschr, _mbschr, _mbschr_l

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at strchr, wcschr, _mbschr, _mbschr_l.

Finds a character in a string, by using the current locale or a specified LC_CTYPE conversion-state category.

Important

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

Syntax

char *strchr(  
   const char *str,  
   int c   
);  // C only  
char *strchr(  
   char * str,  
   int c   
); // C++ only  
const char *strchr(  
   const char * str,  
   int c   
); // C++ only  
wchar_t *wcschr(  
   const wchar_t *str,  
   wchar_t c   
); // C only  
wchar_t *wcschr(  
   wchar_t *str,  
   wchar_t c   
);  // C++ only  
const wchar_t *wcschr(  
   const wchar_t *str,  
   wchar_t c   
);  // C++ only  
unsigned char *_mbschr(  
   const unsigned char *str,  
   unsigned int c   
); // C only  
unsigned char *_mbschr(  
   unsigned char *str,  
   unsigned int c   
); // C++ only  
const unsigned char *_mbschr(  
   const unsigned char *str,  
   unsigned int c   
); // C++ only  
unsigned char *_mbschr_l(  
   const unsigned char *str,  
   unsigned int c,  
   _locale_t locale  
); // C only   
unsigned char *_mbschr_l(  
   unsigned char *str,  
   unsigned int c,  
   _locale_t locale  
); // C++ only  
const unsigned char *_mbschr_l(  
   const unsigned char *str,  
   unsigned int c,  
   _locale_t locale  
); // C++ only

Parameters

str
Null-terminated source string.

c
Character to be located.

locale
Locale to use.

Return Value

Each of these functions returns a pointer to the first occurrence of c in str, or NULL if c is not found.

Remarks

The strchr function finds the first occurrence of c in str, or it returns NULL if c is not found. The null terminating character is included in the search.

wcschr, _mbschr and _mbschr_l are wide-character and multibyte-character versions of strchr. The arguments and return value of wcschr are wide-character strings; those of _mbschr are multibyte-character strings. _mbschr recognizes multibyte-character sequences. Also, if the string is a null pointer, _mbschr invokes the invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, _mbschr returns NULL and sets errno to EINVAL. strchr and wcschr do not validate their parameters. These three functions behave identically otherwise.

The output value is affected by the setting of the LC_CTYPE category setting of the locale; for more information, see setlocale. The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. For more information, see Locale.

In C, these functions take a const pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to const returns a pointer to const; the version that takes a pointer to non-const returns a pointer to non-const. The macro _CONST_CORRECT_OVERLOADS is defined if both the const and non-const versions of these functions are available. If you require the non-const behavior for both C++ overloads, define the symbol _CONST_RETURN.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
`_tcschr`	`strchr`	`_mbschr`	`wcschr`
_n/a	n/a	`_mbschr_l`	n/a

Requirements

Routine	Required header
`strchr`	<string.h>
`wcschr`	<string.h> or <wchar.h>
`_mbschr`, `_mbschr_l`	<mbstring.h>

For more information about compatibility, see Compatibility.

Example

// crt_strchr.c  
//   
// This program illustrates searching for a character  
// with strchr (search forward) or strrchr (search backward).  
//  
  
#include <string.h>  
#include <stdio.h>  
  
int  ch = 'r';  
  
char string[] = "The quick brown dog jumps over the lazy fox";  
char fmt1[] =   "         1         2         3         4         5";  
char fmt2[] =   "12345678901234567890123456789012345678901234567890";  
  
int main( void )  
{  
   char *pdest;  
   int result;  
  
   printf_s( "String to be searched:\n      %s\n", string );  
   printf_s( "      %s\n      %s\n\n", fmt1, fmt2 );  
   printf_s( "Search char:   %c\n", ch );  
  
   // Search forward.   
   pdest = strchr( string, ch );  
   result = (int)(pdest - string + 1);  
   if ( pdest != NULL )  
      printf_s( "Result:   first %c found at position %d\n",   
              ch, result );  
   else  
      printf_s( "Result:   %c not found\n", ch );  
  
   // Search backward.   
   pdest = strrchr( string, ch );  
   result = (int)(pdest - string + 1);  
   if ( pdest != NULL )  
      printf_s( "Result:   last %c found at position %d\n", ch, result );  
   else  
      printf_s( "Result:\t%c not found\n", ch );  
}

String to be searched:  
      The quick brown dog jumps over the lazy fox  
               1         2         3         4         5  
      12345678901234567890123456789012345678901234567890  
  
Search char:   r  
Result:   first r found at position 12  
Result:   last r found at position 30

.NET Framework Equivalent

System::String::IndexOf