idn_enable man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

idn_decodename(3EXT)	  Extended Library Functions	  idn_decodename(3EXT)

NAME
       idn_decodename,	   idn_decodename2,	idn_enable,    idn_encodename,
       idn_nameinit - IDN (Internationalized Domain Name) conversion functions

SYNOPSIS
       cc [ flag... ] file... -lidnkit [ library... ]
       #include <idn/api.h>

       idn_result_t idn_decodename(int actions, const char *from, char *to,
	   size_t tolen);

       idn_result_t idn_decodename2(int actions, const char *from, char *to,
	   size_t tolen, const char *auxencoding);

       idn_result_t idn_encodename(int actions, const char *from, char *to,
	   size_t tolen);

       void idn_enable(int on_off);

       idn_result_t idn_nameinit(int load_file);

DESCRIPTION
       The idn_nameinit() function  initializes	 the  library.	It  also  sets
       default	configuration  if load_file is 0, otherwise it tries to read a
       configuration file. If idn_nameinit() is called	more  than  once,  the
       library initialization will take place only at the first call while the
       actual configuration procedure will occur at every call.

       If there are no errors, idn_nameinit() returns idn_success.  Otherwise,
       the  returned  value  indicates the cause of the error. See the section
       RETURN VALUES below for the error codes.

       It is usually not necessary to call this function explicitly because it
       is   implicitly	called	when  idn_encodename(),	 idn_decodename(),  or
       idn_decodename2()  is   first   called	without	  prior	  calling   of
       idn_nameinit().

       The  idn_encodename()  function	performs name preparation and encoding
       conversion on the internationalized domain name specified by from,  and
       stores  the  result  to	to,  whose  length  is specified by tolen. The
       actions argument is a bitwise-OR of the	following  macros,  specifying
       which subprocesses in the encoding process are to be employed.

       IDN_LOCALCONV	Local encoding to UTF-8 conversion

       IDN_DELIMMAP	Delimiter mapping

       IDN_LOCALMAP	Local mapping

       IDN_NAMEPREP	NAMEPREP  mapping, normalization, prohibited character
			check, and bidirectional string check

       IDN_UNASCHECK	NAMEPREP unassigned codepoint check

       IDN_ASCCHECK	ASCII range character check

       IDN_IDNCONV	UTF-8 to IDN encoding conversion

       IDN_LENCHECK	Label length check

       Details of this encoding process can  be	 found	in  the	 section  Name
       Encoding

       For    convenience,    also   IDN_ENCODE_QUERY,	 IDN_ENCODE_APP,   and
       IDN_ENCODE_STORED macros are  provided.	IDN_ENCODE_QUERY  is  used  to
       encode a ``query string'' (see the IDNA specification). It is equal to:

	 (IDN_LOCALCONV | IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP |
		 IDN_IDNCONV | IDN_LENCHECK)

       IDN_ENCODE_APP  is  used	 for  ordinary	application to encode a domain
       name. It	 performs  IDN_ASCCHECK	 in  addition  with  IDN_ENCODE_QUERY.
       IDN_ENCODE_STORED  is  used to encode a ``stored string'' (see the IDNA
       specification). It performs IDN_ENCODE_APP plus IDN_UNASCHECK.

       The idn_decodename() function performs the reverse of idn_encodename().
       It  converts  the internationalized domain name given by from, which is
       represented in a special encoding called ACE (ASCII  Compatible	Encod‐
       ing), to the application's local codeset and stores in to, whose length
       is specified by tolen. As in idn_encodename(), actions is a  bitwise-OR
       of the following macros.

       IDN_DELIMMAP	Delimiter mapping

       IDN_NAMEPREP	NAMEPREP  mapping, normalization, prohibited character
			check and bidirectional string check

       IDN_UNASCHECK	NAMEPREP unassigned codepoint check

       IDN_IDNCONV	UTF-8 to IDN encoding conversion

       IDN_RTCHECK	Round trip check

       IDN_ASCCHECK	ASCII range character check

       IDN_LOCALCONV	Local encoding to UTF-8 conversion

       Details of this decoding process can  be	 found	in  the	 section  Name
       Decoding.

       For	convenience,	 IDN_DECODE_QUERY,     IDN_DECODE_APP,	   and
       IDN_DECODE_STORED macros are also provided. IDN_DECODE_QUERY is used to
       decode a ``query string'' (see the IDNA specification). It is equal to

	 (IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK | IDN_LOCALCONV)

       IDN_DECODE_APP  is  used	 for  ordinary	application to decode a domain
       name.  It  performs  IDN_ASCCHECK  in  addition	to   IDN_DECODE_QUERY.
       IDN_DECODE_STORED  is  used to decode a ``stored string'' (see the IDNA
       specification). It performs IDN_DECODE_APP plus IDN_UNASCHECK.

       The idn_decodename2()  function	provides  the  same  functionality  as
       idn_decodename()	 except that character encoding of from is supposed to
       be  auxencoding.	 If  IDN  encoding  is	Punycode  and  auxencoding  is
       ISO8859-2,  for	example, it is assumed that the Punycode string stored
       in from is written in ISO8859-2.

       In the IDN decode procedure, IDN_NAMEPREP is done  before  IDN_IDNCONV,
       and  some non-ASCII characters are converted to ASCII characters as the
       result of IDN_NAMEPREP. Therefore, ACE string specified by  from	 might
       contains	 those non-ASCII characters. That is the reason docode_name2()
       exists.

       All of thsee functions return an error value of type idn_result_t.  All
       values other than idn_success indicates some kind of failure.

   Name Encoding
       Name encoding is a process that transforms the specified international‐
       ized domain name to a certain string suitable for name resolution.  For
       each label in a given domain name, the encoding processor performs:

	   1.	  Convert to UTF-8 (IDN_LOCALCONV)

		  Convert  the encoding of the given domain name from applica‐
		  tion's local encoding (for example, ISO8859-1) to UTF-8.

	   2.	  Delimiter mapping (IDN_DELIMMAP)

		  Map domain name delimiters to `.' (U+002E). The reco- ginzed
		  delimiters  are:  U+3002  (ideographic  full	stop),	U+FF0E
		  (fullwidth full stop), U+FF61	 (halfwidth  ideographic  full
		  stop).

	   3.	  Local mapping (IDN_LOCALMAP)

		  Apply character mapping whose rule is determined by the top-
		  level domain name.

	   4.	  NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)

		  Perform name preparation (NAMEPREP),	which  is  a  standard
		  process for name canonicalizaion of internationalized domain
		  names.

		  NAMEPREP consists of 5 steps: mapping,  normalization,  pro‐
		  hibited character check, bidirectional text check, and unas‐
		  signed codepoint check. The first four  steps	 are  done  by
		  IDN_NAMEPREP, and the last step is done by IDN_UNASCHECK.

	   5.	  ASCII range character check (IDN_ASCCHECK)

		  Checks  if the domain name contains non-LDH ASCII characters
		  (not letter, digit, or hyphen characters), or it  begins  or
		  end with hyphen.

	   6.	  Convert to ACE (IDN_IDNCONV)

		  Convert  the	NAMEPREPed name to a special encoding designed
		  for representing internationalized domain names.

		  The encoding is known as  ACE	 (ASCII	 Compatible  Encoding)
		  since	 a  string  in the encoding is just like a traditional
		  ASCII domain name consisting of  only	 letters,  digits  and
		  hyphens.

	   7.	  Label length check (IDN_LENCHECK)

		  For  each  label,  check  the number of characters in it. It
		  must be in the range of 1 to 63.

   Name Decoding
       Name decoding is a reverse process of the name encoding. It  transforms
       the specified internationalized domain name in a special encoding suit‐
       able for name resolution to the normal name string in the application's
       current	codeset. However, name encoding and name decoding are not sym‐
       metric.

       For each label in a given domain name, the decoding processor performs:

	   1.	  Delimiter mapping (IDN_DELIMMAP)

		  Map domain name delimiters to `.' (U+002E).  The  recoginzed
		  delimiters  are:  U+3002  (ideographic  full	stop),	U+FF0E
		  (fullwidth full stop), U+FF61	 (halfwidth  ideographic  full
		  stop).

	   2.	  NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)

		  Perform  name	 preparation  (NAMEPREP),  which is a standard
		  process for name canonicalizaion of internationalized domain
		  names.

	   3.	  Convert to UTF-8 (IDN_IDNCONV)

		  Convert  the	encoding  of the given domain name from ACE to
		  UTF-8.

	   4.	  Round trip check (IDN_RTCHECK)

		  Encode the result of (3) using the  Name   Encoding  scheme,
		  and then compare it with the result of the step (2). If they
		  are  different,  the	check  is  failed.  If	IDN_UNASCHECK,
		  IDN_ASCCHECK	or  both  are specified, they are also done in
		  the encoding processes.

	   5.	  Convert to local encoding

		  Convert the result of (3) from UTF-8	to  the	 application's
		  local encoding (for example, ISO8859-1).

       If  prohibited  character check, unassigned codepoint check or bidirec‐
       tional text check at step (2) failed, or if round trip  check  at  step
       (4) failed, the original input label is returned.

   Disabling IDN
       If your application should always disable internationalized domain name
       support for some reason, call

	 (void) idn_enable(0);

       before performing encoding/decoding. Afterward, you can enable the sup‐
       port by calling

	 (void) idn_enable(1);

RETURN VALUES
       These functions return values of type idn_result_t to indicate the sta‐
       tus of the call. The following is a complete list of the status codes.

       idn_success		Not an error. The call succeeded.

       idn_notfound		Specified information does not exist.

       idn_invalid_encoding	The  encoding  of  the	specified  string   is
				invalid.

       idn_invalid_syntax	There is a syntax error in internal configura‐
				tion file(s).

       idn_invalid_name		The specified name is not valid.

       idn_invalid_message	The specified message is not valid.

       idn_invalid_action	The specified action contains invalid flags.

       idn_invalid_codepoint	The specified Unicode code point value is  not
				valid.

       idn_invalid_length	The  number  of	 characters in an ACE label is
				not in the range of 1 to 63.

       idn_buffer_overflow	The specified buffer is too small to hold  the
				result.

       idn_noentry		The  specified	key does not exist in the hash
				table.

       idn_nomemory		Memory allocation using malloc failed.

       idn_nofile		The specified file could not be opened.

       idn_nomapping		Some characters do not have the mapping to the
				target character set.

       idn_context_required	Context information is required.

       idn_prohibited		The  specified string contains some prohibited
				characters.

       idn_failure		Generic error which  is	 not  covered  by  the
				above codes.

EXAMPLES
       Example 1 Get the address of an internationalized domain name.

       To  get the address of an internationalized domain name in the applica‐
       tion's local codeset, use idn_encodename() to convert the name  to  the
       format suitable for passing to resolver functions.

	 #include <idn/api.h>
	 #include <sys/socket.h>
	 #include <netdb.h>

	 ...

	 idn_result_t r;
	 char ace_name[256];
	 struct hostent *hp;
	 int error_num;

	 ...

	 r = idn_encodename(IDN_ENCODE_APP, name, ace_name,
			   sizeof(ace_name));
	 if (r != idn_success) {
	    fprintf(stderr, gettext("idn_encodename failed.\n"));
	    exit(1);
	 }

	 hp = getipnodebyname(ace_name, AF_INET6, AI_DEFAULT, &error_num);

	 ...

       Example 2 Decode the internationalized domain name.

       To  decode  the	internationalized domain name returned from a resolver
       function, use idn_decodename().

	 #include <idn/api.h>
	 #include <sys/socket.h>
	 #include <netdb.h>

	 ...

	 idn_result_t r;
	 char local_name[256];
	 struct hostent *hp;
	 int error_num;

	 ...

	 hp = getipnodebyname(name, AF_INET, AI_DEFAULT, &error_num);
	 if (hp != (struct hostent *)NULL) {
	     r = idn_decodename(IDN_DECODE_APP, hp->h_name, local_name,
			   sizeof(local_name));
	     if (r != idn_success) {
		  fprintf(stderr, gettext("idn_decodename failed.\n"));
		  exit(1);
	     }
	     printf(gettext("name: %s\n"), local_name);
	 }

	 ...

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWidnl, SUNWidnd	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │CSI			     │Enabled			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Evolving			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Unsafe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       intro(3), libidnkit(3LIB), setlocale(3C), hosts(4), attributes(5), env‐
       iron(5)

       RFC 3490		  Internationalizing   Domain  Names  in  Applications
			  (IDNA)

       RFC 3491		  Nameprep: A Stringprep Profile for Internationalized
			  Domain Names (IDN)

       RFC 3492		  Punycode:  A	Bootstring  encoding  of  Unicode  for
			  Internationalized  Domain  Names   in	  Applications
			  (IDNA)

       RFC 3454		  Preparation  of  Internationalized Strings ("string‐
			  prep")

       RFC 952		  DoD Internet Host Table Specification

       RFC 921		  Domain Name System Implementation Schedule - Revised

       STD 3, RFC 1122	  Requirements for  Internet  Hosts  --	 Communication
			  Layers

       STD 3, RFC 1123	  Requirements	for Internet Hosts -- Applications and
			  Support

       Unicode Standard Annex #15: Unicode Normalization Forms, Version 3.2.0.
       http://www.unicode.org

       International Language Environments Guide (for this version of Solaris)

COPYRIGHT AND LICENSE
       Copyright  (c)  2000-2002 Japan Network Information Center.  All rights
       reserved.

       By using this file, you agree to the terms  and	conditions  set	 forth
       bellow.

       LICENSE TERMS AND CONDITIONS

       The  following  License	Terms and Conditions apply, unless a different
       license is obtained from Japan Network Information Center ("JPNIC"),  a
       Japanese	 association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda,
       Chiyoda-ku, Tokyo 101-0047, Japan.

	   1.	  Use, Modification and Redistribution (including distribution
		  of  any  modified  or	 derived work) in source and/or binary
		  forms is permitted under this License Terms and Conditions.

	   2.	  Redistribution of source  code  must	retain	the  copyright
		  notices  as  they  appear  in	 each  source  code file, this
		  License Terms and Conditions.

	   3.	  Redistribution in binary form must reproduce	the  Copyright
		  Notice, this License Terms and Conditions, in the documenta‐
		  tion and/or other materials provided with the	 distribution.
		  For  the  purposes  of  binary  distribution	the "Copyright
		  Notice" refers to the	 following  language:  "Copyright  (c)
		  2000-2002  Japan  Network  Information  Center.  All	rights
		  reserved."

	   4.	  The name of JPNIC may not be	used  to  endorse  or  promote
		  products  derived  from this Software without specific prior
		  written approval of JPNIC.

	   5.	  Disclaimer/Limitation of Liability: THIS  SOFTWARE  IS  PRO‐
		  VIDED	 BY  JPNIC  "AS	 IS"  AND  ANY EXPRESS OR IMPLIED WAR‐
		  RANTIES, INCLUDING, BUT NOT LIMITED  TO,  THE	 IMPLIED  WAR‐
		  RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR‐
		  POSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE  LIABLE  FOR
		  ANY  DIRECT,	INDIRECT,  INCIDENTAL,	SPECIAL, EXEMPLARY, OR
		  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED  TO,  PRO‐
		  CUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
		  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND  ON
		  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL‐
		  ITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING  IN
		  ANY  WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
		  THE POSSIBILITY OF SUCH DAMAGES.

NOTES
       The idn_nameinit() function checks internal system configuration	 files
       such as /etc/idn/idn.conf and /etc/idn/idnalias.conf if they are in the
       proper access mode and owership. If they are not in the	proper	access
       mode  or	 ownership,  the function will not read and use the configura‐
       tions defined in the files but use default values.  In  this  case  the
       function will also issue a warning message such as:

	 idn_nameinit: warning: config file (/etc/idn/idn.conf) not in proper
			       access mode or ownership - the file ignored.

       The  proper  access mode and the ownership are described in the package
       prototype file of SUNWidnl. It is also recommended not  to  change  the
       system configuration files.

SunOS 5.10			  15 Aug 2003		  idn_decodename(3EXT)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net