xref: /freebsd/lib/libc/string/strstr.3 (revision 3fb3b97c4d38990da5f45b37e48a5110b3e9bc58)
141036d78SMike Barcroft.\" Copyright (c) 2001 Mike Barcroft <mike@FreeBSD.org>
258f0484fSRodney W. Grimes.\" Copyright (c) 1990, 1991, 1993
358f0484fSRodney W. Grimes.\"	The Regents of the University of California.  All rights reserved.
458f0484fSRodney W. Grimes.\"
558f0484fSRodney W. Grimes.\" This code is derived from software contributed to Berkeley by
658f0484fSRodney W. Grimes.\" Chris Torek and the American National Standards Committee X3,
758f0484fSRodney W. Grimes.\" on Information Processing Systems.
858f0484fSRodney W. Grimes.\"
958f0484fSRodney W. Grimes.\" Redistribution and use in source and binary forms, with or without
1058f0484fSRodney W. Grimes.\" modification, are permitted provided that the following conditions
1158f0484fSRodney W. Grimes.\" are met:
1258f0484fSRodney W. Grimes.\" 1. Redistributions of source code must retain the above copyright
1358f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer.
1458f0484fSRodney W. Grimes.\" 2. Redistributions in binary form must reproduce the above copyright
1558f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer in the
1658f0484fSRodney W. Grimes.\"    documentation and/or other materials provided with the distribution.
17*3fb3b97cSEd Maste.\" 3. Neither the name of the University nor the names of its contributors
1858f0484fSRodney W. Grimes.\"    may be used to endorse or promote products derived from this software
1958f0484fSRodney W. Grimes.\"    without specific prior written permission.
2058f0484fSRodney W. Grimes.\"
2158f0484fSRodney W. Grimes.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
2258f0484fSRodney W. Grimes.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
2358f0484fSRodney W. Grimes.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
2458f0484fSRodney W. Grimes.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
2558f0484fSRodney W. Grimes.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
2658f0484fSRodney W. Grimes.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
2758f0484fSRodney W. Grimes.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2858f0484fSRodney W. Grimes.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2958f0484fSRodney W. Grimes.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
3058f0484fSRodney W. Grimes.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
3158f0484fSRodney W. Grimes.\" SUCH DAMAGE.
3258f0484fSRodney W. Grimes.\"
3358f0484fSRodney W. Grimes.\"     @(#)strstr.3	8.1 (Berkeley) 6/4/93
347f3dea24SPeter Wemm.\" $FreeBSD$
3558f0484fSRodney W. Grimes.\"
36a9227c40SMike Barcroft.Dd October 11, 2001
3758f0484fSRodney W. Grimes.Dt STRSTR 3
3858f0484fSRodney W. Grimes.Os
3958f0484fSRodney W. Grimes.Sh NAME
4089503316SAndrey A. Chernov.Nm strstr , strcasestr , strnstr
4158f0484fSRodney W. Grimes.Nd locate a substring in a string
4225bb73e0SAlexey Zelkin.Sh LIBRARY
4325bb73e0SAlexey Zelkin.Lb libc
4458f0484fSRodney W. Grimes.Sh SYNOPSIS
4532eef9aeSRuslan Ermilov.In string.h
4658f0484fSRodney W. Grimes.Ft char *
4758f0484fSRodney W. Grimes.Fn strstr "const char *big" "const char *little"
4841036d78SMike Barcroft.Ft char *
4989503316SAndrey A. Chernov.Fn strcasestr "const char *big" "const char *little"
5089503316SAndrey A. Chernov.Ft char *
5141036d78SMike Barcroft.Fn strnstr "const char *big" "const char *little" "size_t len"
52db356f03SIsabell Long.In string.h
53db356f03SIsabell Long.In xlocale.h
54db356f03SIsabell Long.Ft char *
55db356f03SIsabell Long.Fn strcasestr_l "const char *big" "const char *little" "locale_t loc"
5658f0484fSRodney W. Grimes.Sh DESCRIPTION
5758f0484fSRodney W. GrimesThe
5858f0484fSRodney W. Grimes.Fn strstr
5958f0484fSRodney W. Grimesfunction
6058f0484fSRodney W. Grimeslocates the first occurrence of the null-terminated string
6158f0484fSRodney W. Grimes.Fa little
6258f0484fSRodney W. Grimesin the null-terminated string
6358f0484fSRodney W. Grimes.Fa big .
6441036d78SMike Barcroft.Pp
6541036d78SMike BarcroftThe
6689503316SAndrey A. Chernov.Fn strcasestr
6789503316SAndrey A. Chernovfunction is similar to
68a9227c40SMike Barcroft.Fn strstr ,
6989503316SAndrey A. Chernovbut ignores the case of both strings.
7089503316SAndrey A. Chernov.Pp
7189503316SAndrey A. ChernovThe
72db356f03SIsabell Long.Fn strcasestr_l
73db356f03SIsabell Longfunction does the same as
74db356f03SIsabell Long.Fn strcasestr
75db356f03SIsabell Longbut takes an explicit locale rather than using the current locale.
76db356f03SIsabell Long.Pp
77db356f03SIsabell LongThe
7841036d78SMike Barcroft.Fn strnstr
7941036d78SMike Barcroftfunction
8041036d78SMike Barcroftlocates the first occurrence of the null-terminated string
8141036d78SMike Barcroft.Fa little
8241036d78SMike Barcroftin the string
8341036d78SMike Barcroft.Fa big ,
84a9227c40SMike Barcroftwhere not more than
85a9227c40SMike Barcroft.Fa len
86a9227c40SMike Barcroftcharacters are searched.
87a9227c40SMike BarcroftCharacters that appear after a
88a9227c40SMike Barcroft.Ql \e0
89a9227c40SMike Barcroftcharacter are not searched.
907ec7a350SMike BarcroftSince the
917ec7a350SMike Barcroft.Fn strnstr
927ec7a350SMike Barcroftfunction is a
937ec7a350SMike Barcroft.Fx
941ddfc2e3SRuslan Ermilovspecific API, it should only be used when portability is not a concern.
9541036d78SMike Barcroft.Sh RETURN VALUES
9658f0484fSRodney W. GrimesIf
9758f0484fSRodney W. Grimes.Fa little
9841036d78SMike Barcroftis an empty string,
9941036d78SMike Barcroft.Fa big
10041036d78SMike Barcroftis returned;
10158f0484fSRodney W. Grimesif
10258f0484fSRodney W. Grimes.Fa little
10358f0484fSRodney W. Grimesoccurs nowhere in
10458f0484fSRodney W. Grimes.Fa big ,
1051ddfc2e3SRuslan Ermilov.Dv NULL
1061ddfc2e3SRuslan Ermilovis returned;
10741036d78SMike Barcroftotherwise a pointer to the first character of the first occurrence of
10841036d78SMike Barcroft.Fa little
10941036d78SMike Barcroftis returned.
11041036d78SMike Barcroft.Sh EXAMPLES
11141036d78SMike BarcroftThe following sets the pointer
11241036d78SMike Barcroft.Va ptr
11341036d78SMike Barcroftto the
1141ddfc2e3SRuslan Ermilov.Qq Li Bar Baz
11541036d78SMike Barcroftportion of
11641036d78SMike Barcroft.Va largestring :
11741036d78SMike Barcroft.Bd -literal -offset indent
11841036d78SMike Barcroftconst char *largestring = "Foo Bar Baz";
11941036d78SMike Barcroftconst char *smallstring = "Bar";
12041036d78SMike Barcroftchar *ptr;
12141036d78SMike Barcroft
12241036d78SMike Barcroftptr = strstr(largestring, smallstring);
12341036d78SMike Barcroft.Ed
12441036d78SMike Barcroft.Pp
12541036d78SMike BarcroftThe following sets the pointer
12641036d78SMike Barcroft.Va ptr
1271ddfc2e3SRuslan Ermilovto
1281ddfc2e3SRuslan Ermilov.Dv NULL ,
1291ddfc2e3SRuslan Ermilovbecause only the first 4 characters of
13041036d78SMike Barcroft.Va largestring
13141036d78SMike Barcroftare searched:
13241036d78SMike Barcroft.Bd -literal -offset indent
13341036d78SMike Barcroftconst char *largestring = "Foo Bar Baz";
13441036d78SMike Barcroftconst char *smallstring = "Bar";
13541036d78SMike Barcroftchar *ptr;
13641036d78SMike Barcroft
13741036d78SMike Barcroftptr = strnstr(largestring, smallstring, 4);
13841036d78SMike Barcroft.Ed
13958f0484fSRodney W. Grimes.Sh SEE ALSO
14058f0484fSRodney W. Grimes.Xr memchr 3 ,
1416050c8feSAndre Oppermann.Xr memmem 3 ,
14258f0484fSRodney W. Grimes.Xr strchr 3 ,
14358f0484fSRodney W. Grimes.Xr strcspn 3 ,
14458f0484fSRodney W. Grimes.Xr strpbrk 3 ,
14558f0484fSRodney W. Grimes.Xr strrchr 3 ,
14658f0484fSRodney W. Grimes.Xr strsep 3 ,
14758f0484fSRodney W. Grimes.Xr strspn 3 ,
1485174a6a2SEdward Tomasz Napierala.Xr strtok 3 ,
1495174a6a2SEdward Tomasz Napierala.Xr wcsstr 3
15058f0484fSRodney W. Grimes.Sh STANDARDS
15158f0484fSRodney W. GrimesThe
15258f0484fSRodney W. Grimes.Fn strstr
15358f0484fSRodney W. Grimesfunction
15458f0484fSRodney W. Grimesconforms to
155588a200cSRuslan Ermilov.St -isoC .
156