string/FreeBSD/strstr.3

   1 .\" Copyright (c) 2001 Mike Barcroft <mike@FreeBSD.org>
   2 .\" Copyright (c) 1990, 1991, 1993
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" Chris Torek and the American National Standards Committee X3,
   7 .\" on Information Processing Systems.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)strstr.3    8.1 (Berkeley) 6/4/93
  34 .\" $FreeBSD$
  35 .\"
  36 .Dd October 11, 2001
  37 .Dt STRSTR 3
  38 .Os
  39 .Sh NAME
  40 .Nm strstr , strcasestr , strnstr
  41 .Nd locate a substring in a string
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In string.h
  46 .Ft char *
  47 .Fn strstr "const char *big" "const char *little"
  48 .Ft char *
  49 .Fn strcasestr "const char *big" "const char *little"
  50 .Ft char *
  51 .Fn strnstr "const char *big" "const char *little" "size_t len"
  52 .In string.h
  53 .In xlocale.h
  54 .Ft char *
  55 .Fn strcasestr_l "const char *big" "const char *little" "locale_t loc"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn strstr
  59 function
  60 locates the first occurrence of the null-terminated string
  61 .Fa little
  62 in the null-terminated string
  63 .Fa big .
  64 .Pp
  65 The
  66 .Fn strcasestr
  67 function is similar to
  68 .Fn strstr ,
  69 but ignores the case of both strings.
  70 .Pp
  71 The
  72 .Fn strnstr
  73 function
  74 locates the first occurrence of the null-terminated string
  75 .Fa little
  76 in the string
  77 .Fa big ,
  78 where not more than
  79 .Fa len
  80 characters are searched.
  81 Characters that appear after a
  82 .Ql \e0
  83 character are not searched.
  84 Since the
  85 .Fn strnstr
  86 function is a
  87 .Fx
  88 specific API, it should only be used when portability is not a concern.
  89 .Pp
  90 While the
  91 .Fn strcasestr
  92 function uses the current locale, the
  93 .Fn strcasestr_l
  94 function may be passed a locale directly. See
  95 .Xr xlocale 3
  96 for more information.
  97 .Sh RETURN VALUES
  98 If
  99 .Fa little
 100 is an empty string,
 101 .Fa big
 102 is returned;
 103 if
 104 .Fa little
 105 occurs nowhere in
 106 .Fa big ,
 107 .Dv NULL
 108 is returned;
 109 otherwise a pointer to the first character of the first occurrence of
 110 .Fa little
 111 is returned.
 112 .Sh EXAMPLES
 113 The following sets the pointer
 114 .Va ptr
 115 to the
 116 .Qq Li Bar Baz
 117 portion of
 118 .Va largestring :
 119 .Bd -literal -offset indent
 120 const char *largestring = "Foo Bar Baz";
 121 const char *smallstring = "Bar";
 122 char *ptr;
 123
 124 ptr = strstr(largestring, smallstring);
 125 .Ed
 126 .Pp
 127 The following sets the pointer
 128 .Va ptr
 129 to
 130 .Dv NULL ,
 131 because only the first 4 characters of
 132 .Va largestring
 133 are searched:
 134 .Bd -literal -offset indent
 135 const char *largestring = "Foo Bar Baz";
 136 const char *smallstring = "Bar";
 137 char *ptr;
 138
 139 ptr = strnstr(largestring, smallstring, 4);
 140 .Ed
 141 .Sh SEE ALSO
 142 .Xr memchr 3 ,
 143 .Xr memmem 3 ,
 144 .Xr strchr 3 ,
 145 .Xr strcspn 3 ,
 146 .Xr strpbrk 3 ,
 147 .Xr strrchr 3 ,
 148 .Xr strsep 3 ,
 149 .Xr strspn 3 ,
 150 .Xr strtok 3 ,
 151 .Xr wcsstr 3 ,
 152 .Xr xlocale 3
 153 .Sh STANDARDS
 154 The
 155 .Fn strstr
 156 function
 157 conforms to
 158 .St -isoC .