xref: /freebsd/lib/libc/string/strstr.3 (revision 4d004ccce24ba06f0043503570d1fdbd39c9211f)
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.
173fb3b97cSEd 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
3458f0484fSRodney W. Grimes.\"
35a9227c40SMike Barcroft.Dd October 11, 2001
3658f0484fSRodney W. Grimes.Dt STRSTR 3
3758f0484fSRodney W. Grimes.Os
3858f0484fSRodney W. Grimes.Sh NAME
3989503316SAndrey A. Chernov.Nm strstr , strcasestr , strnstr
4058f0484fSRodney W. Grimes.Nd locate a substring in a string
4125bb73e0SAlexey Zelkin.Sh LIBRARY
4225bb73e0SAlexey Zelkin.Lb libc
4358f0484fSRodney W. Grimes.Sh SYNOPSIS
4432eef9aeSRuslan Ermilov.In string.h
4558f0484fSRodney W. Grimes.Ft char *
4658f0484fSRodney W. Grimes.Fn strstr "const char *big" "const char *little"
4741036d78SMike Barcroft.Ft char *
4889503316SAndrey A. Chernov.Fn strcasestr "const char *big" "const char *little"
4989503316SAndrey A. Chernov.Ft char *
5041036d78SMike Barcroft.Fn strnstr "const char *big" "const char *little" "size_t len"
51db356f03SIsabell Long.In string.h
52db356f03SIsabell Long.In xlocale.h
53db356f03SIsabell Long.Ft char *
54db356f03SIsabell Long.Fn strcasestr_l "const char *big" "const char *little" "locale_t loc"
5558f0484fSRodney W. Grimes.Sh DESCRIPTION
5658f0484fSRodney W. GrimesThe
5758f0484fSRodney W. Grimes.Fn strstr
5858f0484fSRodney W. Grimesfunction
5958f0484fSRodney W. Grimeslocates the first occurrence of the null-terminated string
6058f0484fSRodney W. Grimes.Fa little
6158f0484fSRodney W. Grimesin the null-terminated string
6258f0484fSRodney W. Grimes.Fa big .
6341036d78SMike Barcroft.Pp
6441036d78SMike BarcroftThe
6589503316SAndrey A. Chernov.Fn strcasestr
6689503316SAndrey A. Chernovfunction is similar to
67a9227c40SMike Barcroft.Fn strstr ,
6889503316SAndrey A. Chernovbut ignores the case of both strings.
6989503316SAndrey A. Chernov.Pp
7089503316SAndrey A. ChernovThe
71db356f03SIsabell Long.Fn strcasestr_l
72db356f03SIsabell Longfunction does the same as
73db356f03SIsabell Long.Fn strcasestr
74db356f03SIsabell Longbut takes an explicit locale rather than using the current locale.
75db356f03SIsabell Long.Pp
76db356f03SIsabell LongThe
7741036d78SMike Barcroft.Fn strnstr
7841036d78SMike Barcroftfunction
7941036d78SMike Barcroftlocates the first occurrence of the null-terminated string
8041036d78SMike Barcroft.Fa little
8141036d78SMike Barcroftin the string
8241036d78SMike Barcroft.Fa big ,
83a9227c40SMike Barcroftwhere not more than
84a9227c40SMike Barcroft.Fa len
85a9227c40SMike Barcroftcharacters are searched.
86a9227c40SMike BarcroftCharacters that appear after a
87a9227c40SMike Barcroft.Ql \e0
88a9227c40SMike Barcroftcharacter are not searched.
897ec7a350SMike BarcroftSince the
907ec7a350SMike Barcroft.Fn strnstr
917ec7a350SMike Barcroftfunction is a
927ec7a350SMike Barcroft.Fx
931ddfc2e3SRuslan Ermilovspecific API, it should only be used when portability is not a concern.
9441036d78SMike Barcroft.Sh RETURN VALUES
9558f0484fSRodney W. GrimesIf
9658f0484fSRodney W. Grimes.Fa little
9741036d78SMike Barcroftis an empty string,
9841036d78SMike Barcroft.Fa big
9941036d78SMike Barcroftis returned;
10058f0484fSRodney W. Grimesif
10158f0484fSRodney W. Grimes.Fa little
10258f0484fSRodney W. Grimesoccurs nowhere in
10358f0484fSRodney W. Grimes.Fa big ,
1041ddfc2e3SRuslan Ermilov.Dv NULL
1051ddfc2e3SRuslan Ermilovis returned;
10641036d78SMike Barcroftotherwise a pointer to the first character of the first occurrence of
10741036d78SMike Barcroft.Fa little
10841036d78SMike Barcroftis returned.
10941036d78SMike Barcroft.Sh EXAMPLES
11041036d78SMike BarcroftThe following sets the pointer
11141036d78SMike Barcroft.Va ptr
11241036d78SMike Barcroftto the
1131ddfc2e3SRuslan Ermilov.Qq Li Bar Baz
11441036d78SMike Barcroftportion of
11541036d78SMike Barcroft.Va largestring :
11641036d78SMike Barcroft.Bd -literal -offset indent
11741036d78SMike Barcroftconst char *largestring = "Foo Bar Baz";
11841036d78SMike Barcroftconst char *smallstring = "Bar";
11941036d78SMike Barcroftchar *ptr;
12041036d78SMike Barcroft
12141036d78SMike Barcroftptr = strstr(largestring, smallstring);
12241036d78SMike Barcroft.Ed
12341036d78SMike Barcroft.Pp
12441036d78SMike BarcroftThe following sets the pointer
12541036d78SMike Barcroft.Va ptr
1261ddfc2e3SRuslan Ermilovto
1271ddfc2e3SRuslan Ermilov.Dv NULL ,
1281ddfc2e3SRuslan Ermilovbecause only the first 4 characters of
12941036d78SMike Barcroft.Va largestring
13041036d78SMike Barcroftare searched:
13141036d78SMike Barcroft.Bd -literal -offset indent
13241036d78SMike Barcroftconst char *largestring = "Foo Bar Baz";
13341036d78SMike Barcroftconst char *smallstring = "Bar";
13441036d78SMike Barcroftchar *ptr;
13541036d78SMike Barcroft
13641036d78SMike Barcroftptr = strnstr(largestring, smallstring, 4);
13741036d78SMike Barcroft.Ed
13858f0484fSRodney W. Grimes.Sh SEE ALSO
13958f0484fSRodney W. Grimes.Xr memchr 3 ,
1406050c8feSAndre Oppermann.Xr memmem 3 ,
14158f0484fSRodney W. Grimes.Xr strchr 3 ,
14258f0484fSRodney W. Grimes.Xr strcspn 3 ,
14358f0484fSRodney W. Grimes.Xr strpbrk 3 ,
14458f0484fSRodney W. Grimes.Xr strrchr 3 ,
14558f0484fSRodney W. Grimes.Xr strsep 3 ,
14658f0484fSRodney W. Grimes.Xr strspn 3 ,
1475174a6a2SEdward Tomasz Napierala.Xr strtok 3 ,
1485174a6a2SEdward Tomasz Napierala.Xr wcsstr 3
14958f0484fSRodney W. Grimes.Sh STANDARDS
15058f0484fSRodney W. GrimesThe
15158f0484fSRodney W. Grimes.Fn strstr
15258f0484fSRodney W. Grimesfunction
15358f0484fSRodney W. Grimesconforms to
154588a200cSRuslan Ermilov.St -isoC .
155*4d004cccSDavid E. O'Brien.Sh HISTORY
156*4d004cccSDavid E. O'BrienThe
157*4d004cccSDavid E. O'Brien.Fn strnstr
158*4d004cccSDavid E. O'Brienfunction was introduced by
159*4d004cccSDavid E. O'Brien.Fx 4.5
160*4d004cccSDavid E. O'Brienand is non-standard.
161