locale/mbrune.3

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Paul Borman at Krystal Technologies.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)mbrune.3    8.2 (Berkeley) 4/19/94
  36 .\" $FreeBSD: src/lib/libc/locale/mbrune.3,v 1.15 2003/02/06 11:04:46 charnier Exp $
  37 .\"
  38 .Dd April 19, 1994
  39 .Dt MBRUNE 3
  40 .Os
  41 .Sh NAME
  42 .Nm mbrune ,
  43 .Nm mbrrune ,
  44 .Nm mbmb
  45 .Nd multibyte rune support for C
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In rune.h
  50 .Ft char *
  51 .Fn mbrune "const char *string" "rune_t rune"
  52 .Ft char *
  53 .Fn mbrrune "const char *string" "rune_t rune"
  54 .Ft char *
  55 .Fn mbmb "const char *string" "char *pattern"
  56 .Sh DESCRIPTION
  57 .Bf Em
  58 The
  59 .Bx 4.4
  60 .Dq rune
  61 functions have been deprecated in favour of the
  62 .Tn ISO
  63 C99 extended multibyte and wide character facilities
  64 and should not be used in new applications.
  65 .Ef
  66 Consider working with wide characters instead, and using
  67 .Xr wcschr 3 ,
  68 .Xr wcsrchr 3 ,
  69 and
  70 .Xr wcsstr 3
  71 instead of these functions.
  72 .Pp
  73 These routines provide the corresponding functionality of
  74 .Fn strchr ,
  75 .Fn strrchr
  76 and
  77 .Fn strstr
  78 for multibyte strings.
  79 .Pp
  80 The
  81 .Fn mbrune
  82 function locates the first occurrence of
  83 .Fn rune
  84 in the string pointed to by
  85 .Fa string .
  86 The terminating
  87 .Dv NUL
  88 character is considered part of the string.
  89 If
  90 .Fa rune
  91 is
  92 .Ql \e0 ,
  93 .Fn mbrune
  94 locates the terminating
  95 .Ql \e0 .
  96 .Pp
  97 The
  98 .Fn mbrrune
  99 function
 100 locates the last occurrence of
 101 .Fa rune
 102 in the string
 103 .Fa string .
 104 If
 105 .Fa rune
 106 is
 107 .Ql \e0 ,
 108 .Fn mbrune
 109 locates the terminating
 110 .Ql \e0 .
 111 .Pp
 112 The
 113 .Fn mbmb
 114 function locates the first occurrence of the null-terminated string
 115 .Fa pattern
 116 in the null-terminated string
 117 .Fa string .
 118 If
 119 .Fa pattern
 120 is the empty string,
 121 .Fn mbmb
 122 returns
 123 .Fa string ;
 124 if
 125 .Fa pattern
 126 occurs nowhere in
 127 .Fa string ,
 128 .Fn mbmb
 129 returns
 130 .Dv NULL ;
 131 otherwise
 132 .Fn mbmb
 133 returns a pointer to the first character of the first occurrence of
 134 .Fa pattern .
 135 .Sh RETURN VALUES
 136 The function
 137 .Fn mbrune
 138 returns a pointer to the located character, or
 139 .Dv NULL
 140 if the character does not appear in the string.
 141 .Pp
 142 The
 143 .Fn mbrrune
 144 function
 145 returns a pointer to the character, or
 146 .Dv NULL
 147 if the character does not appear in the string.
 148 .Pp
 149 The
 150 .Fn mbmb
 151 function
 152 returns a pointer to the
 153 .Fa pattern ,
 154 or
 155 .Dv NULL
 156 if the
 157 .Fa pattern
 158 does not appear in the string.
 159 .Sh SEE ALSO
 160 .Xr rune 3 ,
 161 .Xr setlocale 3 ,
 162 .Xr euc 4 ,
 163 .Xr utf2 4 ,
 164 .Xr utf8 5
 165 .Sh HISTORY
 166 The
 167 .Fn mbrune ,
 168 .Fn mbrrune ,
 169 and
 170 .Fn mbmb
 171 functions
 172 first appeared in Plan 9 from Bell Labs as
 173 .Fn utfrune ,
 174 .Fn utfrrune ,
 175 and
 176 .Fn utfutf .