lib/libc/string/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: head/lib/libc/string/strstr.3 251069 2013-05-28 20:57:40Z emaste $
  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 strcasestr_l
  73 function does the same as
  74 .Fn strcasestr
  75 but takes an explicit locale rather than using the current locale.
  76 .Pp
  77 The
  78 .Fn strnstr
  79 function
  80 locates the first occurrence of the null-terminated string
  81 .Fa little
  82 in the string
  83 .Fa big ,
  84 where not more than
  85 .Fa len
  86 characters are searched.
  87 Characters that appear after a
  88 .Ql \e0
  89 character are not searched.
  90 Since the
  91 .Fn strnstr
  92 function is a
  93 .Fx
  94 specific API, it should only be used when portability is not a concern.
  95 .Sh RETURN VALUES
  96 If
  97 .Fa little
  98 is an empty string,
  99 .Fa big
 100 is returned;
 101 if
 102 .Fa little
 103 occurs nowhere in
 104 .Fa big ,
 105 .Dv NULL
 106 is returned;
 107 otherwise a pointer to the first character of the first occurrence of
 108 .Fa little
 109 is returned.
 110 .Sh EXAMPLES
 111 The following sets the pointer
 112 .Va ptr
 113 to the
 114 .Qq Li Bar Baz
 115 portion of
 116 .Va largestring :
 117 .Bd -literal -offset indent
 118 const char *largestring = "Foo Bar Baz";
 119 const char *smallstring = "Bar";
 120 char *ptr;
 121
 122 ptr = strstr(largestring, smallstring);
 123 .Ed
 124 .Pp
 125 The following sets the pointer
 126 .Va ptr
 127 to
 128 .Dv NULL ,
 129 because only the first 4 characters of
 130 .Va largestring
 131 are searched:
 132 .Bd -literal -offset indent
 133 const char *largestring = "Foo Bar Baz";
 134 const char *smallstring = "Bar";
 135 char *ptr;
 136
 137 ptr = strnstr(largestring, smallstring, 4);
 138 .Ed
 139 .Sh SEE ALSO
 140 .Xr memchr 3 ,
 141 .Xr memmem 3 ,
 142 .Xr strchr 3 ,
 143 .Xr strcspn 3 ,
 144 .Xr strpbrk 3 ,
 145 .Xr strrchr 3 ,
 146 .Xr strsep 3 ,
 147 .Xr strspn 3 ,
 148 .Xr strtok 3 ,
 149 .Xr wcsstr 3
 150 .Sh STANDARDS
 151 The
 152 .Fn strstr
 153 function
 154 conforms to
 155 .St -isoC .