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 .\" 4. 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: src/lib/libc/string/strstr.3,v 1.15 2009/04/07 13:42:53 trasz Exp $
  35 .\"
  36 .Dd October 11, 2001
  37 .Dt STRSTR 3
  38 .Os
  39 .Sh NAME
  40 .Nm strcasestr ,
  41 .Nm strcasestr_l ,
  42 .Nm strnstr ,
  43 .Nm strstr
  44 .Nd locate a substring in a string
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In string.h
  49 .Ft char *
  50 .Fo strcasestr
  51 .Fa "const char *s1"
  52 .Fa "const char *s2"
  53 .Fc
  54 .Ft char *
  55 .Fo strnstr
  56 .Fa "const char *s1"
  57 .Fa "const char *s2"
  58 .Fa "size_t n"
  59 .Fc
  60 .Ft char *
  61 .Fo strstr
  62 .Fa "const char *s1"
  63 .Fa "const char *s2"
  64 .Fc
  65 .In string.h
  66 .In xlocale.h
  67 .Ft char *
  68 .Fo strcasestr_l
  69 .Fa "const char *s1"
  70 .Fa "const char *s2"
  71 .Fa "locale_t loc"
  72 .Fc
  73 .Sh DESCRIPTION
  74 The
  75 .Fn strstr
  76 function
  77 locates the first occurrence of the null-terminated string
  78 .Fa s2
  79 in the null-terminated string
  80 .Fa s1 .
  81 .Pp
  82 The
  83 .Fn strcasestr
  84 function is similar to
  85 .Fn strstr ,
  86 but ignores the case of both strings.
  87 .Pp
  88 The
  89 .Fn strnstr
  90 function
  91 locates the first occurrence of the null-terminated string
  92 .Fa s2
  93 in the string
  94 .Fa s1 ,
  95 where not more than
  96 .Fa n
  97 characters are searched.
  98 Characters that appear after a
  99 .Ql \e0
 100 character are not searched.
 101 Since the
 102 .Fn strnstr
 103 function is a
 104 .Fx
 105 specific API, it should only be used when portability is not a concern.
 106 .Pp
 107 While the
 108 .Fn strcasestr
 109 function uses the current locale, the
 110 .Fn strcasestr_l
 111 function may be passed a locale directly. See
 112 .Xr xlocale 3
 113 for more information.
 114 .Sh RETURN VALUES
 115 If
 116 .Fa s2
 117 is an empty string,
 118 .Fa s1
 119 is returned;
 120 if
 121 .Fa s2
 122 occurs nowhere in
 123 .Fa s1 ,
 124 .Dv NULL
 125 is returned;
 126 otherwise a pointer to the first character of the first occurrence of
 127 .Fa s2
 128 is returned.
 129 .Sh EXAMPLES
 130 The following sets the pointer
 131 .Va ptr
 132 to the
 133 .Qq Li Bar Baz
 134 portion of
 135 .Va largestring :
 136 .Bd -literal -offset indent
 137 const char *largestring = "Foo Bar Baz";
 138 const char *smallstring = "Bar";
 139 char *ptr;
 140
 141 ptr = strstr(largestring, smallstring);
 142 .Ed
 143 .Pp
 144 The following sets the pointer
 145 .Va ptr
 146 to
 147 .Dv NULL ,
 148 because only the first 4 characters of
 149 .Va largestring
 150 are searched:
 151 .Bd -literal -offset indent
 152 const char *largestring = "Foo Bar Baz";
 153 const char *smallstring = "Bar";
 154 char *ptr;
 155
 156 ptr = strnstr(largestring, smallstring, 4);
 157 .Ed
 158 .Sh SEE ALSO
 159 .Xr memchr 3 ,
 160 .Xr strchr 3 ,
 161 .Xr strcspn 3 ,
 162 .Xr strpbrk 3 ,
 163 .Xr strrchr 3 ,
 164 .Xr strsep 3 ,
 165 .Xr strspn 3 ,
 166 .Xr strtok 3 ,
 167 .Xr wcsstr 3 ,
 168 .Xr xlocale 3
 169 .Sh STANDARDS
 170 The
 171 .Fn strstr
 172 function
 173 conforms to
 174 .St -isoC .