[unix-history] / usr / src / lib / libc / string / string.3

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)string.3	4.1 (Berkeley) %G%
.\"
.TH STRING 3 
.UC 4
.SH NAME
strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex \- string operations
.SH SYNOPSIS
.nf
.B char *strcat(s1, s2)
.B char *s1, *s2;
.PP
.B char *strncat(s1, s2, n)
.B char *s1, *s2;
.PP
.B strcmp(s1, s2)
.B char *s1, *s2;
.PP
.B strncmp(s1, s2, n)
.B char *s1, *s2;
.PP
.B char *strcpy(s1, s2)
.B char *s1, *s2;
.PP
.B char *strncpy(s1, s2, n)
.B char *s1, *s2;
.PP
.B strlen(s)
.B char *s;
.PP
.B char *index(s, c)
.B char *s, c;
.PP
.B char *rindex(s, c)
.B char *s, c;
.fi
.SH DESCRIPTION
These functions operate on null-terminated strings.
They do not check for overflow of any receiving string.
.PP
.I Strcat
appends a copy of string
.I s2
to the end of string
.IR s1 .
.I Strncat
copies at most
.I n
characters.
Both return a pointer to the null-terminated result.
.PP
.I Strcmp
compares its arguments and returns an integer
greater than, equal to, or less than 0,
according as
.I s1
is lexicographically greater than, equal to, or
less than
.IR s2 .
.I Strncmp
makes the same comparison but looks at at most
.I n
characters.
.PP
.I Strcpy
copies string
.I s2
to
.I s1,
stopping after the null character has been moved.
.I Strncpy
copies exactly
.I n
characters,
truncating or null-padding
.I s2;
the target may not be null-terminated if the length
of
.I s2
is
.I n
or more.
Both return
.IR s1 .
.PP
.I Strlen
returns the number of non-null characters in
.IR s .
.PP
.I Index
.RI ( rindex )
returns a pointer to the first (last)
occurrence of character 
.I c
in string
.I s,
or zero if
.I c
does not occur in  the string.
.SH BUGS
.I Strcmp 
uses native character comparison, which is signed
on PDP11's and VAX-11's, unsigned on other machines.
Commit	Line	Data
2fe842cb KM	1	.\" Copyright (c) 1980 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
	5	.\" @(#)string.3 4.1 (Berkeley) %G%
	6	.\"
	7	.TH STRING 3
	8	.UC 4
	9	.SH NAME
	10	strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex \- string operations
	11	.SH SYNOPSIS
	12	.nf
	13	.B char *strcat(s1, s2)
	14	.B char s1, s2;
	15	.PP
	16	.B char *strncat(s1, s2, n)
	17	.B char s1, s2;
	18	.PP
	19	.B strcmp(s1, s2)
	20	.B char s1, s2;
	21	.PP
	22	.B strncmp(s1, s2, n)
	23	.B char s1, s2;
	24	.PP
	25	.B char *strcpy(s1, s2)
	26	.B char s1, s2;
	27	.PP
	28	.B char *strncpy(s1, s2, n)
	29	.B char s1, s2;
	30	.PP
	31	.B strlen(s)
	32	.B char *s;
	33	.PP
	34	.B char *index(s, c)
	35	.B char *s, c;
	36	.PP
	37	.B char *rindex(s, c)
	38	.B char *s, c;
	39	.fi
	40	.SH DESCRIPTION
	41	These functions operate on null-terminated strings.
	42	They do not check for overflow of any receiving string.
	43	.PP
	44	.I Strcat
	45	appends a copy of string
	46	.I s2
	47	to the end of string
	48	.IR s1 .
	49	.I Strncat
	50	copies at most
	51	.I n
	52	characters.
	53	Both return a pointer to the null-terminated result.
	54	.PP
	55	.I Strcmp
	56	compares its arguments and returns an integer
	57	greater than, equal to, or less than 0,
	58	according as
	59	.I s1
	60	is lexicographically greater than, equal to, or
	61	less than
	62	.IR s2 .
	63	.I Strncmp
	64	makes the same comparison but looks at at most
65	.I n
66	characters.
67	.PP
68	.I Strcpy
69	copies string
70	.I s2
71	to
72	.I s1,
73	stopping after the null character has been moved.
74	.I Strncpy
75	copies exactly
76	.I n
77	characters,
78	truncating or null-padding
79	.I s2;
80	the target may not be null-terminated if the length
81	of
82	.I s2
83	is
84	.I n
85	or more.
86	Both return
87	.IR s1 .
88	.PP
89	.I Strlen
90	returns the number of non-null characters in
91	.IR s .
92	.PP
93	.I Index
94	.RI ( rindex )
95	returns a pointer to the first (last)
96	occurrence of character
97	.I c
98	in string
99	.I s,
100	or zero if
101	.I c
102	does not occur in the string.
103	.SH BUGS
104	.I Strcmp
105	uses native character comparison, which is signed
106	on PDP11's and VAX-11's, unsigned on other machines.