man/man3/string.3

   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    6.1 (Berkeley) 5/15/85
   6 .\"
   7 .TH STRING 3  "May 15, 1985"
   8 .UC 4
   9 .SH NAME
  10 string, strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, strrchr, strerror, memcmp, memcpy, memmove, memchr, memset, index, rindex \- string operations
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <string.h>
  15
  16 char *strcat(char *\fIs1\fP, const char *\fIs2\fP)
  17 char *strncat(char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP)
  18 int strcmp(const char *\fIs1\fP, const char *\fIs2\fP)
  19 int strncmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP)
  20 char *strcpy(char *\fIs1\fP, const char *\fIs2\fP)
  21 char *strncpy(char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP)
  22 size_t strlen(const char *\fIs\fP)
  23 char *strchr(const char *\fIs\fP, int \fIc\fP)
  24 char *strrchr(const char *\fIs\fP, int \fIc\fP)
  25 char *strerror(int \fIerrnum\fP)
  26 int memcmp(const void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP)
  27 void *memcpy(void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP)
  28 void *memmove(void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP)
  29 void *memchr(const void *\fIs\fP, int \fIc\fP, size_t \fIn\fP)
  30 void *memset(void *\fIs\fP, int \fIc\fP, size_t \fIn\fP)
  31 char *index(const char *\fIs\fP, int \fIc\fP)
  32 char *rindex(const char *\fIs\fP, int \fIc\fP)
  33 .ft R
  34 .fi
  35 .SH DESCRIPTION
  36 These functions operate on null-terminated strings.
  37 They do not check for overflow of any receiving string.
  38 .PP
  39 .B Strcat
  40 appends a copy of string
  41 .I s2
  42 to the end of string
  43 .IR s1 .
  44 .B Strncat
  45 copies at most
  46 .I n
  47 characters.  Both return a pointer to the null-terminated result.
  48 .PP
  49 .B Strcmp
  50 compares its arguments and returns an integer
  51 greater than, equal to, or less than 0, according as
  52 .I s1
  53 is lexicographically greater than, equal to, or less than
  54 .IR s2 .
  55 .B Strncmp
  56 makes the same comparison but looks at at most
  57 .I n
  58 characters.
  59 .PP
  60 .B Strcpy
  61 copies string
  62 .I s2
  63 to
  64 .IR s1 ,
  65 stopping after the null character has been moved.
  66 .B Strncpy
  67 copies exactly
  68 .I n
  69 characters, truncating or null-padding
  70 .I s2;
  71 the target may not be null-terminated if the length of
  72 .I s2
  73 is
  74 .I n
  75 or more.  Both return
  76 .IR s1 .
  77 .PP
  78 .B Strlen
  79 returns the number of non-null characters in
  80 .IR s .
  81 .PP
  82 .B Strchr
  83 .RB ( strrchr )
  84 returns a pointer to the first (last) occurrence of character
  85 .I c
  86 in string
  87 .I s,
  88 or null if
  89 .I c
  90 does not occur in the string.
  91 .PP
  92 .B Strerror
  93 returns the error string for the system call error
  94 .IR errnum .
  95 See
  96 .BR intro (2).
  97 .PP
  98 .B Memcmp
  99 is like
 100 .B strcmp
 101 except that the strings are memory blocks of length
 102 .IR n .
 103 Null characters are treated as ordinary characters.
 104 .PP
 105 .B Memcpy
 106 copies
 107 .I n
 108 bytes from the location pointed to by
 109 .I s2
 110 to
 111 .IR s1 .
 112 .B Memmove
 113 is like memcpy, except that it can handle overlap between the two strings.
 114 Both functions return
 115 .IR s1 .
 116 .PP
 117 .B Memchr
 118 returns a pointer to the first occurrence of character
 119 .I c
 120 in string
 121 .I s,
 122 or null if
 123 .I c
 124 does not occur in the string.
 125 .PP
 126 .B Memset
 127 sets
 128 .I n
 129 bytes to
 130 .I c
 131 starting at location
 132 .IR s .
 133 It returns
 134 .IR s .
 135 .PP
 136 .B Index
 137 and
 138 .B rindex
 139 are obsolete versions of
 140 .B strchr
 141 and
 142 .BR strrchr .
 143 New code should avoid using them.
 144 .SH NOTES
 145 Characters are compared as
 146 .BR "unsigned char" ,
 147 whether
 148 .B char
 149 itself is signed or not.