[BACK]Return to iconv.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / iconv

Annotation of src/lib/libc/iconv/iconv.3, Revision 1.14

1.14    ! wiz         1: .\" $NetBSD: iconv.3,v 1.13 2010/05/05 06:04:19 jruoho Exp $
1.1       tshiozak    2: .\"
                      3: .\" Copyright (c)2003 Citrus Project,
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
                     14: .\"
                     15: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
                     16: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     17: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     18: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
                     19: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     20: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     21: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     22: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     23: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     24: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     25: .\" SUCH DAMAGE.
                     26: .\"
1.13      jruoho     27: .Dd May 5, 2010
1.2       wiz        28: .Dt ICONV 3
1.1       tshiozak   29: .Os
                     30: .\" ----------------------------------------------------------------------
                     31: .Sh NAME
                     32: .Nm iconv_open ,
                     33: .Nm iconv_close ,
                     34: .Nm iconv
                     35: .Nd codeset conversion functions
                     36: .\" ----------------------------------------------------------------------
                     37: .Sh LIBRARY
                     38: .Lb libc
                     39: .\" ----------------------------------------------------------------------
                     40: .Sh SYNOPSIS
                     41: .In iconv.h
                     42: .Ft iconv_t
1.2       wiz        43: .Fn iconv_open "const char *dstname" "const char *srcname"
1.1       tshiozak   44: .Ft int
                     45: .Fn iconv_close "iconv_t cd"
                     46: .Ft size_t
1.12      tshiozak   47: .Fn iconv "iconv_t cd" "const char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft"
1.1       tshiozak   48: .\" ----------------------------------------------------------------------
                     49: .Sh DESCRIPTION
                     50: The
                     51: .Fn iconv_open
                     52: function opens a converter from the codeset
                     53: .Fa srcname
                     54: to the codeset
                     55: .Fa dstname
                     56: and returns its descriptor.
                     57: .Pp
                     58: The
                     59: .Fn iconv_close
1.2       wiz        60: function closes the specified converter
1.1       tshiozak   61: .Fa cd .
                     62: .Pp
                     63: The
                     64: .Fn iconv
1.2       wiz        65: function converts the string in the buffer
1.1       tshiozak   66: .Fa *src
1.2       wiz        67: of length
1.1       tshiozak   68: .Fa *srcleft
1.2       wiz        69: bytes and stores the converted string in the buffer
1.1       tshiozak   70: .Fa *dst
1.2       wiz        71: of size
1.1       tshiozak   72: .Fa *dstleft
                     73: bytes.
                     74: After calling
                     75: .Fn iconv ,
1.2       wiz        76: the values pointed to by
1.1       tshiozak   77: .Fa src ,
                     78: .Fa srcleft ,
1.2       wiz        79: .Fa dst ,
1.1       tshiozak   80: and
                     81: .Fa dstleft
1.2       wiz        82: are updated as follows:
1.13      jruoho     83: .Bl -tag -width 01234567 -offset indent
                     84: .It Fa *src
1.1       tshiozak   85: Pointer to the byte just after the last character fetched.
1.13      jruoho     86: .It Fa *srcleft
1.2       wiz        87: Number of remaining bytes in the source buffer.
1.13      jruoho     88: .It Fa *dst
1.1       tshiozak   89: Pointer to the byte just after the last character stored.
1.13      jruoho     90: .It Fa *dstleft
1.2       wiz        91: Number of remainder bytes in the destination buffer.
1.1       tshiozak   92: .El
                     93: .Pp
1.2       wiz        94: If the string pointed to by
1.1       tshiozak   95: .Fa *src
1.2       wiz        96: contains a byte sequence which is not a valid character in the source
1.1       tshiozak   97: codeset, the conversion stops just after the last successful conversion.
1.2       wiz        98: If the output buffer is too small to store the converted
1.1       tshiozak   99: character, the conversion also stops in the same way.
1.2       wiz       100: In these cases, the values pointed to by
1.1       tshiozak  101: .Fa src ,
                    102: .Fa srcleft ,
1.2       wiz       103: .Fa dst ,
1.1       tshiozak  104: and
                    105: .Fa dstleft
1.2       wiz       106: are updated to the state just after the last successful conversion.
1.1       tshiozak  107: .Pp
1.2       wiz       108: If the string pointed to by
1.1       tshiozak  109: .Fa *src
1.9       wiz       110: contains a character which is valid under the source codeset but
1.1       tshiozak  111: can not be converted to the destination codeset,
1.2       wiz       112: the character is replaced by an
                    113: .Dq invalid character
                    114: which depends on the destination codeset, e.g.,
                    115: .Sq \&? ,
                    116: and the conversion is continued.
1.1       tshiozak  117: .Fn iconv
1.2       wiz       118: returns the number of such
                    119: .Dq invalid conversions .
1.1       tshiozak  120: .Pp
1.7       tshiozak  121: If the source and/or destination codesets are stateful,
                    122: .Fn iconv
                    123: places these into their initial state.
1.13      jruoho    124: There are two special cases of
                    125: .Fn iconv :
                    126: .Bl -enum -offset indent
                    127: .It
1.7       tshiozak  128: If both
                    129: .Fa dst
                    130: and
                    131: .Fa *dst
1.9       wiz       132: are
1.8       wiz       133: .No non- Ns Dv NULL ,
1.7       tshiozak  134: .Fn iconv
                    135: stores the shift sequence for the destination switching to the initial state
                    136: in the buffer pointed to by
1.1       tshiozak  137: .Fa *dst .
1.5       wiz       138: The buffer size is specified by the value pointed to by
1.4       tshiozak  139: .Fa dstleft
1.5       wiz       140: as above.
1.4       tshiozak  141: .Fn iconv
                    142: will fail if the buffer is too small to store the shift sequence.
1.13      jruoho    143: .It
1.7       tshiozak  144: On the other hand,
                    145: .Fa dst
                    146: or
                    147: .Fa *dst
1.8       wiz       148: may be
                    149: .Dv NULL .
                    150: In this case, the shift sequence for the destination switching
1.7       tshiozak  151: to the initial state is discarded.
1.1       tshiozak  152: .El
                    153: .\" ----------------------------------------------------------------------
                    154: .Sh RETURN VALUES
1.2       wiz       155: Upon successful completion of
1.1       tshiozak  156: .Fn iconv_open ,
1.2       wiz       157: it returns a conversion descriptor.
                    158: Otherwise,
1.1       tshiozak  159: .Fn iconv_open
1.13      jruoho    160: returns (iconv_t)\-1 and sets
                    161: .Va errno
                    162: to indicate the error.
1.1       tshiozak  163: .Pp
1.2       wiz       164: Upon successful completion of
1.1       tshiozak  165: .Fn iconv_close ,
                    166: it returns 0.
                    167: Otherwise,
                    168: .Fn iconv_close
1.2       wiz       169: returns \-1 and sets errno to indicate the error.
1.1       tshiozak  170: .Pp
1.2       wiz       171: Upon successful completion of
1.1       tshiozak  172: .Fn iconv ,
1.2       wiz       173: it returns the number of
                    174: .Dq invalid
                    175: conversions.
1.1       tshiozak  176: Otherwise,
                    177: .Fn iconv
1.2       wiz       178: returns (size_t)\-1 and sets errno to indicate the error.
1.1       tshiozak  179: .\" ----------------------------------------------------------------------
                    180: .Sh ERRORS
                    181: The
                    182: .Fn iconv_open
1.9       wiz       183: function may cause an error in the following cases:
1.1       tshiozak  184: .Bl -tag -width Er
                    185: .It Bq Er EINVAL
                    186: There is no converter specified by
                    187: .Fa srcname
                    188: and
                    189: .Fa dstname .
1.14    ! wiz       190: .It Bq Er ENOMEM
        !           191: Memory is exhausted.
1.1       tshiozak  192: .El
                    193: .Pp
                    194: The
                    195: .Fn iconv_close
1.9       wiz       196: function may cause an error in the following case:
1.1       tshiozak  197: .Bl -tag -width Er
                    198: .It Bq Er EBADF
                    199: The conversion descriptor specified by
                    200: .Fa cd
                    201: is invalid.
                    202: .El
                    203: .Pp
                    204: The
                    205: .Fn iconv
1.9       wiz       206: function may cause an error in the following cases:
1.1       tshiozak  207: .Bl -tag -width Er
1.14    ! wiz       208: .It Bq Er E2BIG
        !           209: The output buffer pointed to by
        !           210: .Fa *dst
        !           211: is too small to store the result string.
1.1       tshiozak  212: .It Bq Er EBADF
                    213: The conversion descriptor specified by
                    214: .Fa cd
                    215: is invalid.
                    216: .It Bq Er EILSEQ
1.2       wiz       217: The string pointed to by
1.1       tshiozak  218: .Fa *src
1.2       wiz       219: contains a byte sequence which does not describe a valid character of
1.1       tshiozak  220: the source codeset.
                    221: .It Bq Er EINVAL
1.2       wiz       222: The string pointed to by
1.1       tshiozak  223: .Fa *src
1.2       wiz       224: terminates with an incomplete character or shift sequence.
1.1       tshiozak  225: .El
                    226: .\" ----------------------------------------------------------------------
                    227: .Sh SEE ALSO
                    228: .Xr iconv 1
                    229: .\" ----------------------------------------------------------------------
                    230: .Sh STANDARDS
                    231: .Fn iconv_open ,
1.2       wiz       232: .Fn iconv_close ,
1.1       tshiozak  233: and
                    234: .Fn iconv
                    235: conform to
                    236: .St -p1003.1-2001 .
1.2       wiz       237: .\" ----------------------------------------------------------------------
                    238: .Sh BUGS
                    239: If
                    240: .Fn iconv
                    241: is aborted due to the occurrence of some error,
                    242: the
                    243: .Dq invalid conversion
                    244: count mentioned above is unfortunately lost.

CVSweb <webmaster@jp.NetBSD.org>