strchr, wcschr, _mbschr, _mbschr_l

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

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 isn't found.

Remarks

The strchr function finds the first occurrence of c in str, or it returns NULL if c isn't 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. The arguments and return value 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 don't 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 _CRT_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.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Generic-text routine mappings

Requirements

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

See also

String manipulation
Locale
Interpretation of multibyte-character sequences
strcspn, wcscspn, _mbscspn, _mbscspn_l
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strstr, wcsstr, _mbsstr, _mbsstr_l