The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/docs/xpg4.inf

OS/2 Help File | 1994-02-27 | 120.4 KB | 5,231 lines

ΓòÉΓòÉΓòÉ 1. XPG4 Internationalization (I18N) for OS/2 ΓòÉΓòÉΓòÉ

=============================================================
XPG/4 Internationalization For OS/2              January 1994
=============================================================

               Copyright IBM Corporation -- 1993, 1994

    DISCLAIMER: This package has been made available solely to
    gauge OS/2 Developer interest in XPG/4 Internationalization
    programming model and does not mean that IBM will introduce
    a product based on what is contained in this package.


ΓòÉΓòÉΓòÉ 1.1. Overview ΓòÉΓòÉΓòÉ

XPG4 Internationalization (I18N) consists of a set of APIs, commands and locale
.dll's.  This SDF contains lists of these items as well as the programming
guidelines for using them effectively.

The XPG4 library is based on a locale model, where the world is divided up into
a collection of locales. A given country may have one or more locales depending
on its cultural diversity. A locale is a combination of language and country
monetary, time and character sorting conventions. The best example of the
locale model is Switzerland which has German, Italian, and Swiss locales, since
it is a trilingual country.
Recommended Reading

The Library of NLS recommends the following books:

 GG24-3850   ITSC AIX 3.2 Natl Language Support

 SC23-2431   Internationalization of AIX Software: A Programmer's Guide

 XOPEN       XPG/4 CAE Specification, Issue 4

 Use of SETLOCALE

 By design, an application program initially starts up in the default C locale.
 Upon calling the setlocale routine, the program's locale is determined by
 either the LANG, and LC_* environment variables, or directly by the 2nd
 argument to setlocale.

  #include <wchar.h>

  main() {

      // The LC_ALL and LANG environment variables set the program's locale

      (void)setlocale(LC_ALL, "");
      }

 Setlocale can also be used to query what locale is currently active for a
 given LC_* value, by providing a NULL 2nd argument.
 Use of WCHAR_T

 The wchar_t datatype extends the range of the standard char datatype to 16-bit
 characters. In general programmers only need to use this datatype when direct
 character manipulation is needed on multi-byte character data. Special
 functions are provided to convert between multi-byte and wchar strings, (see
 mbstowcs and wcstombs functions below) and to copy, compare, or search wchar
 strings (see wcs* functions below).
 Use of CHAR

 The char datatype is still used in most cases but now it may contain
 multi-byte characters as defined in the specific locale. A multi-byte
 character is composed of one or more bytes, with no imbedded null bytes. The
 standard C str* functions are used to manipulate these kinds of strings.
 Environment Variables

 The following environment variables are used for internationalization to
 determine the behavior of the system after calling the setlocale() API.  The
 variables are set as defaults by the application at boot time in CONFIG.SYS or
 directly via the SET command.

 LOCPATH         specifies the search path for the localized .dll's including
                 binary locale files, converters, and message files.

 LANG =value     where value is the file name of the locale .dll, e.g. the
                 value En_US is American English.  Values are provided in the
                 "List of locales provided in the library" section.

 NLSPATH         specifies the search path for locating the message catalo
                 files.  The environment variable is used by the Message
                 Facility component of the NLS subsystem.
 Locale values can also be set by the LC_* environment variables.

 LC_ALL          overrides the value of other LC_* environment variables

 LC_COLLATE      determines the character-collation or string-collation rules
                 governing the behavior of ranges, equivalence classes and
                 multicharacter collating elements.

 LC_CTYPE        determines character handling rules governing the
                 interpretation of sequences of bytes of text data characters
                 (single- byte or multi-byte characters), the classification of
                 characters (for example, alpha, digit and so on) and the
                 behavior of character classes.

 LC_MESSAGES     determines the locale (language) for messages and menus.  It
                 also determines the rules for affirmative and negative
                 responses according to locale, although such responses are not
                 recommended by NLS Guidelines or CUA.

 LC_MONETARY     determines the rules governing monetary formatting.

 LC_NUMERIC      determines the rules governing numeric formatting other than
                 monetary.

 LC_TIME         determines the rules governing date and time formatting.

 The application should use only the LANG, LOCPATH and NLSPATH variables.  A
 user can override them with the locale environment variables.  The settings
 are queried for priority level as follows:

   1. If the LC_ALL environment variable is set, the value of the LC_ALL
      variable is used for all categories.

   2. If the LC_ALL environment variable is not set, the values specified for
      medium-priority environment variables (LC_COLLATE, LC_CTYPE, LC_MESSAGES,
      LC_MONETARY, LC_NUMERIC, LC_TIME) are used.

   3. If individual LC_* environment variables are not set, the value of the
      LANG environment variable specifies the locale for all remaining
      categories.

   4. If the LANG environment variable is not set, the locale for all remaining
      categories defaults to the C locale.

 List of locales provided in the library

 Note:  CP/CS means codepage/character set.

 Locale value Language and Territory
 C           Provides hard links to the English catalogs for those program
             products that do not provide default message text strings.
 De_DE       German in Germany (and Austria)
 En_GB       English in the U.K.
 En_US       English in the U.S.
 Es_ES       Spanish in Spain
 Fr_FR       French in France
 It_IT       Italian in Italy
 Jp_JP       Japanese in Japan

 List of OS/2 commands provided:

 gencat          constructs message cat files

 mkcatdefs       constructs message #define .H files

 runcat          script to construct message cat files and associated .H files
                 (via mkcatdefs + gencat)

 List of functions provided in the library

   1. Runtime Locale Load/Query Function:


                char *setlocale(int, const char *);

   2. Messages Catalog Functions:


                nl_catd   catopen(const char *name, int oflag);
                char     *catgets(nl_catd catd, int setid, int msgid, const char *s);
                int       catclose(nl_catd catd);

   3. File I/O functions:


                wint_t   fgetwc(FILE *stream);
                wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);

                wint_t   fputwc(wint_t wc, FILE *stream);
                int      fputws(const wchar_t *ws, FILE *stream);

                wint_t   getwc (FILE *stream);
                wint_t   putwc(wint_t wc, FILE *stream);
                wint_t   ungetwc(wint_t wc, FILE *stream);

                wint_t   getwchar(void);
                wint_t   putwchar(wint_t wc);

   4. I/O Conversion Functions:


                iconv_t iconv_open(const char *tocode, const char *fromcode);

                size_t  iconv(iconv_t cd, const char **inbuf, size_t *inbytesleft,
                                                char **outbuf, size_t *outbytesleft);

                int     iconv_close(iconv_t *cd);

   5. Character Attribute testing (Uses locale-based methods):


               int isalnum(int c);
               int isalpha(int c);
               int iscntrl(int c);
               int isdigit(int c);
               int isgraph(int c);
               int islower(int c);
               int isprint(int c);
               int ispunct(int c);
               int isspace(int c);
               int isupper(int c);
               int isxdigit(int c);

               int toupper(int c);
               int tolower(int c);

               int iswalnum(wint_t wc);
               int iswalpha(wint_t wc);
               int iswcntrl(wint_t wc);
               int iswdigit(wint_t wc);
               int iswgraph(wint_t wc);
               int iswlower(wint_t wc);
               int iswprint(wint_t wc);
               int iswpunct(wint_t wc);
               int iswspace(wint_t wc);
               int iswupper(wint_t wc);
               int iswxdigit(wint_t wc);

               int iswctype(wint_t wc, wctype_t mask);

               wint_t towupper(wint_t wc);
               wint_t towlower(wint_t wc);

               wctype_t wctype(const char *charclass);

   6. The basic conversion methods for multibyte and wchar_t:


                int    mblen(const char *s, size_t n);
                size_t mbstowcs(wchar_t *ws, const char *s, size_t n);
                int    mbtowc(wchar_t *wc, const char *s, size_t n);
                size_t wcstombs(char *s, const wchar_t *ws, size_t n);
                int    wcswidth(const wchar_t *ws, size_t n);
                int    wctomb(char *s, wchar_t wchar);
                int    wcwidth(wint_t wc);

   7. Formatted I/O Functions:


                fscanf/scanf/sscanf with %ws, %wc decoding, and parameter
                                    reordering via the (%n$x) format

                fprintf/printf/sprintf with %ws, %wc encoding, and parameter
                                       reordering via the (%n$x) format

   8. Collations:


                int strcoll(const char *s1, const char *s2);
                size_t strxfrm(char *s1, const char *s2, size_t n);

                int wcscoll(const wchar_t *ws1, const wchar_t *ws2);
                size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);

   9. Date and Time Formatting:


                size_t strftime(char *s, size_t maxsize, const char *format,
                                const struct tm *tm);

                size_t strfmon(char *s, size_t maxsize, const char *format, ...);

                char  *strptime(const char *buf, const char *fmt, struct tm *tm);

                size_t wcsftime(wchar_t *wcs, size_t maxsize, const char *format,
                                const struct tm *tm);

                char *nl_langinfo(nl_item item);
                struct lconv *localeconv(void);

                long wcstol(const wchar_t *nptr,
                                  wchar_t **endptr, int base);

                unsigned long wcstoul(const wchar_t *nptr,
                                            wchar_t **endptr, int base);

  10. Basic String manipulation API for wchar_t data type:


                size_t   wcscspn (const wchar_t *ws1, const wchar_t *ws2);
                size_t   wcslen  (const wchar_t *ws);
                wchar_t *wcscat  (wchar_t       *ws1, const wchar_t *ws2);
                wchar_t *wcscpy  (wchar_t       *ws1, const wchar_t *ws2);
                int      wcscmp  (const wchar_t *ws1, const wchar_t *ws2);
                int      wcsncmp (const wchar_t *ws1, const wchar_t *ws2, size_t n);
                wchar_t *wcspbrk (const wchar_t *ws1, const wchar_t *ws2);
                wchar_t *wcsncpy (wchar_t       *ws1, const wchar_t *ws2, size_t n);
                size_t   wcsspn  (const wchar_t *ws1, const wchar_t *ws2);
                wchar_t *wcschr  (wchar_t       *ws1, wint_t         wc);
                wchar_t *wcsncat (wchar_t       *ws1, const wchar_t *ws2, size_t n);
                wchar_t *wcsrchr (wchar_t       *ws1, wint_t         wc);
                wchar_t *wcstok  (wchar_t       *ws1, const wchar_t *ws2);
                wchar_t *wcswcs  (const wchar_t *ws1, const wchar_t *ws2);


ΓòÉΓòÉΓòÉ 2. SetLocale ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 2.1. SetLocale -- Defines the Program's Locale ΓòÉΓòÉΓòÉ


Syntax

#include <locale.h>

char *setlocale(int category, const char *locale);

Description

The setlocale function changes or queries variables, defined in the locale.h
header file, that indicate location.  The values for category are listed below.

 Category        Purpose

 LC_ALL          Names entire locale of program.

 LC_COLLATE      Affects behavior of the strcoll and strxfrm functions.

 LC_CTYPE        Affects behavior of the character handling functions (See IS*
                 functions)

 LC_MESSAGES     Affects message information (See CatGets functions)

 LC_MONETARY     Affects monetary information (See strfmon functions)

 LC_NUMERIC      Affects the decimal-point character for the formatted
                 input/output and string conversion functions, and the
                 nonmonetary formatting information returned by the localeconv
                 function.

 LC_TIME         Affects behavior of the strftime function.

 You can set the value of locale to:

 "C"       Default C locale

 ""        Environment defined locale

 "De_DE"   German in Germany

 "En_GB"   English in Great Britain

 "En_US"   English in the United States

 "Es_ES"   Spanish in Spain

 "Fr_FR"   French in France

 "It_IT"   Italian in Italy

 "Jp_JP"   Japanese in Japan

 A locale value of "C" indicates the default C environment.  A locale value of
 "" tells setlocale to use the default locale for the implementation.

 The setlocale function returns a pointer to the string associated with the
 specified category for the new locale.  The string can be used on a subsequent
 call to restore that part of the program's locale.

 Note:  Because the string to which a successful call to setlocale points may
 be overwritten by subsequent calls to the setlocale function, you should copy
 the string if you plan to use it later.

 On error, the setlocale function returns NULL and the program's locale is not
 changed.

 To query the locale, give a NULL as the second parameter.  For example, to
 query all the categories of your locale, enter the following statement:


      char *string = setlocale(LC_ALL, NULL);


 Related Information

   o  getenv  - Search for Environment Variables
   o  localeconv  - Query Locale Conventions
   o  _putenv - Modify Environment Variables
   o  locale.h

 Example of setlocale

  #include <stdio.h>
  #include <locale.h>

  char *string;

  int main(void) {

     string = setlocale(LC_ALL, "");     /* adopt parent session locale */

     if (string != NULL) printf(" %s \n",string);   /* show what it is */
  }

 This example sets the locale of the program to be what the session is and
 prints the string that is associated with the locale. If LANG were set to
 En_US, then the program would display:


      En_US En_US En_US En_US En_US En_US


ΓòÉΓòÉΓòÉ 3. Message Catalog Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 3.1. CATOPEN -- Opens a specified message catalog ΓòÉΓòÉΓòÉ


Syntax

#include <nl_types.h>

nl_catd catopen(const char *name, int oflag);

Description

The catopen subroutine opens a specified message catalog and returns a catalog
descriptor used to retrieve messages from the catalog. The contents of the
catalog descriptor are complete when the catgets subroutine accesses the
message catalog.  The nl_catd data type is used for catalog descriptors. This
data type is defined in the nl_types.h file.

If the catalog file name referred to by the CatalogName parameter contains a
drive letter on a leading \, it is assumed to be an absoute pathname.  If the
catalog file  name  is  not  an  absolute path name,  the user environment
determines which directory  paths to search.  The NLSPATH environment variable
defines the directory search path.  When this variable is used, the setlocale
subroutine must be called before the catopen subroutine.

You can use two special variables, %N and %L, in the NLSPATH environment
variable.  The %N variable is replaced by the catalog name referred to by the
call that opens the message catalog.  The %L variable is replaced by the value
of the LC_MESSAGES category.

The value of the LC_MESSAGES category can be set by specifying values for the
LANG, LC_ALL, or LC_MESSAGES environment variable.  The value of the
LC_MESSAGES category indicates which locale specific directory to search for
message catalogs.  For example, if the catopen subroutine specifies a catalog
with the name mycmd, and the environment variables are set as follows:

    NLSPATH=..\%N:.\%N:\system\nls\%L\%N:\system\nls\%N
    LANG=Fr_FR

then the application searches for the catalog in the following order:

   o  ..\mycmd

   o  .\mycmd

   o  \system/\ls\Fr_FR\mycmd

   o  \system\nls\mycmd
 If you omit the %N variable in a directory specification within the NLSPATH
 environment variable, the application assumes that the path defines a
 directory and searches for the catalog in that directory before searching the
 next specified path.

 If the NLSPATH environment variable is not defined, the default path of
 \usr\lib\nls\msg\%L\%N;\usr\lib\nls\msg\prime\ %N is used.  If the LC_MESSAGES
 category is set to the C locale(LC_MESSAGES=C), then the NLSPATH variable
 mechanism is disabled.  Subsequent calls to the catgets subroutine generate
 pointers to the program-supplied default text.
 Parameters

 CatalogNameSpecifies the catalog file to open.

 Parameter Included for compatibility with X/Open, but not used by this
           operating system.  Use a value of 0.

 Return Values

 The catopen subroutine returns a catalog descriptor.  If the LC_MESSAGES
 category is set to the default value C, the catopen subroutine returns a value
 of -1.

 If the LC_MESSAGES category is not set to C but the catopen subroutine returns
 a value of -1, an error has occurred during creation of the nl_catd structure.
 Error Codes

 EACCES    Read permission is denied for the message catalog or search
           permission is denied for the component of the path prefix of the
           message catalog.

 EMFILE    There are OPEN_MAX file descriptors currently open.

 ENAMETOOLONG The pathname component is longer than NAME_MAX or the length of
           the pathname of the message catalog exceeds PATH_MAX.

 ENFILE    Too many files open in the system.

 ENOENT    The name argument points to an empty string or the message catalog
           does not exist.

 ENOMEM    There is not enough storage space available.

 ENOTDIR   File is not found in the directory.

 Related Information

   o  catclose - close a message catalog file.
   o  catgets - read a message.
   o  setlocale - envoke a locale.

 Example

  #include<nl_types.h>

  void load_cat(char *tcat) {
      nl_catd catd;         /*---- catalog descriptor ----*/
      char cat[PATH_MAX];

      if (strchr(tcat,'\')) {
        strcpy(cat,tcat);
        }

      else {
        sprintf(cat,".\%s",tcat);
        }

      if (access(cat,R_OK)) return;     /* check to see if cat file exists */

      if ((catd = catopen( cat , 0)) == CATD_ERR) {
        printf("Unable to load specified catalog. \n");
        exit (1);
        }

      if(catclose(catd)==-1)
        perror("Error when trying to close catalog file");

      }


ΓòÉΓòÉΓòÉ 3.2. CATGETS -- Retrieves a message from a catalog ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

char *catgets(nl_catd catd, int setid, int msgid, const char *s);

Description

The catgets subroutine retrieves a message from a catalog and constructs a
message based on the setid + mesid + message. If the catgets subroutine finds
the specified message, it loads it into an internal character string  buffer,
ends the  message  string with a null character, and returns a pointer to the
buffer.

The returned pointer is used to reference the buffer and display the message.
However, the buffer can not be referenced after the catalog is closed.
Parameters

 CatalogDescriptorSpecifies a catalog description that is returned by the
           catopen subroutine.

 SetNumber Specifies the set ID.

 MessageNumberSpecifies the message ID.  The SetNumber and MessageNumber
           parameters specify a particular message in the catalog to retrieve.

 String    Specifies the default character-string buffer.

 Return Value

 If the catgets subroutine is unsuccessful for any reason, it returns the
 user-supplied  default  message string specified by the String parameter.
 Related Information

   o  catclose - close a message catalog.
   o  catopen - open a message catalog.
   o  nl_types.h - header file for message functions.

 Example

  #include<nl_types.h>

  char *catg(char *tcat, int setno, int msgno, char *def) {
      nl_catd catd;         /*---- catalog descriptor ----*/
      char cat[PATH_MAX];

      if (strchr(tcat,'\')) {
        strcpy(cat,tcat);
        }

      else {
        sprintf(cat,".\%s",tcat);
        }

      if (access(cat,R_OK)) return;     /* if cat file exists --> return */

      if ((catd = catopen( cat , 0)) == CATD_ERR) {
        printf("Unable to load specified catalog. \n");
        exit (1);
        }

      catgets(catd, setno, msgno, def);

      printf("ERROR MESSAGE : %s\n",def);

      if (catclose(catd)==-1)
        perror("Error when trying to close catalog file");

      }

 This example opens a message file with the name contained in tcat and prints
 out the message associated with set number in setno and the message number in
 msgno.


ΓòÉΓòÉΓòÉ 3.3. CATCLOSE -- closes a specified message catalog ΓòÉΓòÉΓòÉ


Syntax

#include <nl_types.h>

int catclose(nl_catd catd);

Description

The function catclose is used to close the catalog message file specified by
the parameter "catd", that was previously opened by catopen.  Successful return
is 0.  Unsuccessful return is -1 and ERRNO is set.
Related Information

   o  catgets - read a message from the message catalog.
   o  catopen - open a message catalog.
   o  nl_types.h.

 Example

  #include<nl_types.h>

  void load_cat(char *tcat) {
      nl_catd catd;         /*---- catalog descriptor ----*/
      char cat[PATH_MAX];

      if (strchr(tcat,'\')) {
        strcpy(cat,tcat);
      }
      else {
        sprintf(cat,".\%s",tcat);
      }

      if (access(cat,R_OK)) return;  /* check to see if cat file exists */

      if ((catd = catopen( cat , 0)) == CATD_ERR) {
        printf("Unable to load specified catalog. \n");
        exit (1);
        }

      if (catclose(catd)==-1)
        perror("Error when trying to close catalog file");

      }

 This example opens and closes a catalog message file.


ΓòÉΓòÉΓòÉ 4. File I/O Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4.1. FGETWC -- Read a single WCHAR character ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wint_t fgetwc(FILE *stream);

Description

The fgetwc function reads a single multi-byte character from the input stream
at the current position, returns it in wide character format and advances the
associated file pointer, if any, so that it points to the next wide character.

The fgetwc function returns the character read as an  wint_t.  An WEOF return
value indicates an error or an end-of-file condition.  Use feof or ferror to
determine whether the WEOF value indicates an error or the end of the file.
Related Information

   o  feof  - Test End-of-File Indicator
   o  ferror  - Test for Read/Write Errors
   o  fopen  - Open File
   o  wchar

 Example

  #include <wchar.h>
  #include <stdio.h>
  #define  MAX_LEN  26

  int main(void) {
      FILE *stream;
      wchar_t buffer[MAX_LEN + 1];
      size_t i;
      wint_t ch;

      stream = fopen("myfile.dat","r");

      for (i = 0;((i < MAX_LEN)
        && ((ch =  fgetwc(stream)) != WEOF)
        && (ch != '\n')); i++)
           buffer[i] = ch;

      buffer[i] = NULL;

      printf("%S",buffer);

      if (fclose(stream)) perror("fclose error");

    }
  /***************  If myfile.dat contains  ********************

           ABCDEFGHIJKLMNOPQRSTUVWXYZ1000000A0.013400

  *******************  expected output is:  ********************

  ABCDEFGHIJKLMNOPQRSTUVWXYZ

 This example gathers a single line of input from a stream.


ΓòÉΓòÉΓòÉ 4.2. FGETWS -- Read a string of wide characters ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *fgetws (wchar_t *ws, int n, FILE *stream);

Description

The fgetws function reads multibyte characters from the current stream position
up to and including the first new-line character (\n), up to the end of the
stream, or until the number of characters read is equal to n-1, whichever comes
first.  The fgetws  function stores the result in string and adds a null
character (\0) to the end of the string.  The string includes the new-line
character, if read.  If n is equal to 1, the string contains a wide character
new-line only.

The fgetws function returns a pointer to the string buffer if successful.  A
NULL return value indicates an error or an end-of-file condition.  Use feof or
ferror to determine whether the NULL value indicates an error or the end of the
file. In either case, the value of the string is unchanged.  See fgetwc for
possible returned errors.
Related Information

   o  feof  - Test End-of-File Indicator.
   o  ferror  - Test for Read/Write Errors.
   o  fputws  - Print Strings.
   o  wchar.h  - include file for the wide character functions.

 Example

  #include <stdio.h>
  #include <wchar.h>
  #define  MAX_LEN  27

  int main(void) {
      FILE *stream;
      wchar_t line[MAX_LEN], *result;

      stream = fopen("myfile.dat","rb");

      if ((result = fgetws(line,MAX_LEN,stream)) != NULL)
        printf("The string is %S\n", result);

      if (fclose(stream)) perror("fclose error");
      }

  ****************  If myfile.dat contains  ********************

           ABCDEFGHIJKLMNOPQRSTUVWXYZ1000000A0.013400

  *******************  expected output is:  ********************

  The string is ABCDEFGHIJKLMNOPQRSTUVWXYZ

 This example gets a line of input from a data stream. The example reads no
 more than MAX_LEN - 1 characters, or up to a new-line character, from the
 stream.


ΓòÉΓòÉΓòÉ 4.3. FPUTWC -- Write one wide character to stream ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>  /* needed when running Cset2 */

wint_t fputwc(wint_t wc, FILE *stream);

Description

The fputwc function converts the wide character wc to an multibyte character
and then writes the multibyte character to the output stream at the current
position and advances the file position appropriately. If the stream is opened
with one of the append modes, the character is appended to the end of the
stream.

The fputwc function normally returns the character written. A return value of
WEOF indicates an error.
Related Information

   o  fgetwc  - Read a Wide Character.
   o  putwc  - Write a Wide Character.
   o  wchar.h  -  Header file for wide character prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>
  #define NUM_ALPHA  80
  int main(void) {
      FILE * stream;
      int i;
      wint_t ch;

      wchar_t buffer[NUM_ALPHA];

      mbstowcs(buffer,"abcdefghijklmnopqrstuvwxyz",NUM_ALPHA);

      if (( stream = fopen("myfile.dat", "w"))!= NULL ) {
        for (i=0; i<(int)wcslen(buffer); ++i)   /* Put buffer into file */
        ch=fputwc(buffer[i], stream);
        fclose( stream );
        }

      else perror( "Error opening myfile.dat" );

      }

 This example writes the contents of buffer to a file called myfile.dat.

 Note:  Because the output occurs as a side effect within the second expression
 of the for statement, the statement body is null.


ΓòÉΓòÉΓòÉ 4.4. FPUTWS -- Write a Wide Character String to Stream ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>  /* needed when running Cset2 */

int fputws(const wchar_t *string, FILE *stream);

Description

The fputws function copies string to the output stream at the current position.
It does not copy the NULL character (\0) at the end of the string.

If an error occurs, the fputws function returns EOF and set errno;  otherwise,
it returns a non-negative value.
Related Information

   o  fgetws  - Read a String
   o  wchar.h  -  Header file for wide character prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>
  #define NUM_ALPHA  80
  int main(void) {
      FILE * stream;
      int num;
      wint_t ch;

      wchar_t buffer[NUM_ALPHA];

      mbstowcs(buffer,"abcdefghijklmnopqrstuvwxyz",NUM_ALPHA);

      if ((stream=fopen("myfile.dat", "w")) != NULL) {
        num=fputws(buffer, stream);    /* Put buffer into file */

        /* Note that fputws() does not copy the NULL character */

        printf( "Total number of characters written to file = %i\n", num );

        fclose( stream );
        }

      else perror( "Error opening myfile.dat" );
      }

 This example writes a string to a stream.


ΓòÉΓòÉΓòÉ 4.5. GETWC -- Reads data from stream ΓòÉΓòÉΓòÉ


Syntax

#include <sdtio.h>
#include <wchar.h>  /* required if using Cset2 */

wint_t getwc(FILE *stream);

Dscription.

The getwc function reads a single wide character from the current stream
position and advances the stream position to the next wide character.

The getwc function returns the character read.  A return value of WEOF
indicates an error or end-of-file condition.  Errno will be set if any error
occurs.
Related Information

   o  fgetwc  - Read a Wide Character.
   o  putwc - Write a Wide Character.
   o  wchar.h  - Header file for Wide Character Prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define LINE 80

  int main(void) {
      wchar_t buffer[LINE+1];
      int i;
      wint_t ch;

      printf( "Please enter string\n" );

      /*
      Keep reading until either:
      1. the length of LINE is exceeded  or
      2. the input character is EOF  or
      3. the input character is a new-line character
      */

      for (i=0; (i < LINE) && ((ch=getwc()) != EOF)
        && (ch!='\n'); ++i)
          buffer[i] = ch;

      buffer[i]=NULL;                 /* NULL terminator for string */

      printf( "The string is %ls\n", buffer );
      }

  /****************  Output should be similar to:  ******************

  Please enter string
  hello world
  The string is hello world

  *******************************************************************/

 This example gets a line of input from the stdin stream. You can also use
 getwc(stdin) instead of getchar() in the for statement to get a line of input
 from stdin.


ΓòÉΓòÉΓòÉ 4.6. GETWCHAR -- Gets a wide character from an input stream ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wint_t getwchar(void);

Description

The getwchar subroutine is equivalent to the getwc subroutine with stdin as the
input stream.

The getwchar subroutine returns the next wide character from the input stream
pointed to by stdin.  Errno is set to the following if an error occurs: ENOMEM
Storage space is insufficient. ENXIO  The process sent a request to a
nonexistent device, or the device cannot handle the request. EILSEQ  The wc
wide character code does not correspond to a valid character.
Related Information

   o  getwc  - Get a wide character.
   o  fgetwc  -  Get a wide character from the input stream.
   o  wchar.h  - Header file for wide character prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>
  int main (void) {
      wint_t ch;

      printf("\nType in some letters.");
      printf("\n");

      for(;;) {
        ch = getwchar();
        putwchar(ch);
        }

      return 1;
      }

 This example gets wide characters from the keyboard and echoes them back to
 the screen.


ΓòÉΓòÉΓòÉ 4.7. PUTWC -- Writes a wide character to the output stream ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>

wint_t putwc(wint_t wc, FILE *stream);

Description

The putwc function converts wc to wide char and then writes wc to the output
stream at the current position.

The putwc function returns the character written. A return value of WEOF
indicates an error.
Related Information

   o  fputwc  - Write a Wide Character
   o  getwc - getchar - Read a Wide Character
   o  putws  - Write a Wide String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>
  #include <lc_core.h>

  int main(void) {
      FILE *stream = stdout;
      int i;
      wchar_t ws[200];
      char *s = "hello world";

      mbstowcs(ws, s, strlen(s));

      for ( i = 0; i < wcslen(ws); i++ )
        if (putwc(ws[i], stream) == WEOF) {
          perror("Stream I/O Failure");
          break;
          }

      }

  /********************  Expected output:  **************************

  Hello world

  *******************************************************************/

 This example writes the contents of a buffer to a data stream.  In this
 example, the body of the for statement is null because the example carries out
 the writing operation in the test expression.


ΓòÉΓòÉΓòÉ 4.8. PUTWCHAR -- Writes a wide character to a stream ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wint_t putwchar(wint_t wc);

Description

The putwchar subroutine works like the putwc subroutine, except that putwchar
writes the specified wide character to the standard output.  Output streams,
with the exception of stderr, are buffered by default if they refer to files,
or line-buffered if they refer  to terminals.

Upon successful completion, the putwc, putwchar, and fputwc subroutines return
the wide character that is  written.  OtherwiseWEOF is returned, the error
indicator for the stream is set, and the errno global variable is set to:
EAGAIN  The O_NONBLOCK flag is set for the file descriptor under lying the
Stream parameter, delaying the process during the write operation.  EBADF  The
file descriptor underlying the Stream parameter is not valid and cannot be
updated during the write operation.  EFBIG  The process attempted to write to a
file that already equals or exceeds the file-size limit for the process.  EINTR
The process has received a signal that terminates the read operation.  EIO
The process is in a background process group attempting to perform  a  write
operation  to  its  controlling terminal.  The TOSTOP flag is set, the process
is not ignoring or blocking the SIGTTOU flag, and the process group of the
process is orphaned.  ENOSPC  No free space remains on the device containing
the file.  ENOMEM  Insufficient storage space available.  ENXIO  A request was
made of a non-existant device, or the request was outside the capabilities of
the device.  EILSEQ  The wide-character code does not correspond to a valid
character.
Related Information

   o  fputwc  - Put a wide character out to a stream.
   o  putwc  - Put a wide character to std out.
   o  wchar.h  - Header file for wide character prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>
  int main (void) {
      wint_t ch;

      cprintf("\nType in some letters.");
      printf("\n");
      for(;;) {
        ch = getwchar();
        putwchar(ch);
        }

      return 1;
      }

 This example gets wide characters from the keyboard and prints them out using
 putwchar.


ΓòÉΓòÉΓòÉ 4.9. UNGETWC -- Push wide-character onto input stream ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>

wint_t ungetwc(wint_t wc, FILE *stream);

Description

The ungetwc function pushes the wide character pointed to by wc back onto the
given input stream.  However, only one sequential ungetwc is guaranteed to be
pushed back onto the input stream if you call ungetwc consecutively. The stream
must be open for reading.  A subsequent read operation on the stream starts
with wc.  You cannot push WEOF back on the stream using ungetwc.

Characters placed on the stream by ungetwc will be erased if a fseek, fsetpos,
rewind, or fflush function is called before the character is read from the
stream.
Related Information

   o  getwc - Read a Wide Character
   o  putwc - Write a Wide Character
   o  wchar.h

 Example

  #include <stdio.h>
  #include <ctype.h>
  #include <wchar.h>

  int main(void) {
      FILE *stream;
      int ch;
      unsigned int result = 0;

      while ((ch = getc(stream)) != EOF && isdigit(ch))
        result = result * 10 + ch - '0';

      if (ch != EOF) ungetwc(ch,stream);
      }

 In this example, the while statement reads decimal digits from an input data
 stream by using arithmetic statements to compose the numeric values of the
 numbers as it reads them.  When a nondigit character appears before the endof
 the file, ungetwc replaces it in the input stream so that later input
 functions can process it.


ΓòÉΓòÉΓòÉ 5. ICONV Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1. ICONV_OPEN -- Access to conversion descriptor ΓòÉΓòÉΓòÉ


Syntax

#include <iconv.h>

iconv_t iconv_open(const char *target, const char *source);

Description

The iconv_open function is used to obtain an iconv_t descriptor that describes
the conversion from the source code set to the target code set. For state
dependant conversions, icon_open starts in the initial unshifted state.
Related Information

   o  iconv  - Converts string of char from one character code set to another.
   o  iconv_close  - Deallocates all resources allocated by iconv_open.
   o  iconv.h  - Header file for iconv prototypes.

 Example

  See iconv for example.


ΓòÉΓòÉΓòÉ 5.2. ICONV -- Converts string of char from one character code set to another ΓòÉΓòÉΓòÉ


Syntax

#include <iconv.h>

size_t iconv(iconv_t CD, const char **InBuf, size_t *InBytesLeft,
             char **OutBuf, size_t *OutBytesLeft);

 CD        Specifies the conversion descriptor that points to the correct code
           set converter.

 InBuf     Points to a buffer that contains the number of bytes in InBytesLeft
           to be converted.

 InBytesLeft Points to an integer that contains the number of bytes in InBuf.

 OutBuf    Points to a buffer that contains the number of bytes in OutBytesLeft
           that have been converted.

 OutBytesLeft Points to an integer that contains the number of bytes in OutBuf.

 Description

 The iconv subroutine converts the string specified by the InBuf parameter into
 a  different  code set and returns the results in the OutBuf parameter.  The
 required conversion method is identified by the CD parameter, which must be a
 valid conversion descriptor returned  by  a  previous, successful call to the
 iconv_open subroutine.

 On calling, the InBytesLeft parameter indicates the number of bytes in the
 InBuf buffer to be converted, and the OutBytesLeft parameter indicates the
 number of available bytes in the OutBuf buffer.  These  values are updated
 upon return so they indicate the new state of their associated buffers.  For
 state-dependent encodings, calling the iconv subroutine with the InBuf buffer
 set to null will reset the conversion descriptor in the CD parameter to its
 initial state. Subsequent calls with the InBuf buffer, specifying other than a
 NULL pointer, may cause the internal state of the subroutine to be altered as
 necessary.  Upon successful conversion of all the characters in the InBuf
 buffer and after placing the converted characters in the OutBuf buffer, the
 iconv subroutine returns 0, updates the InBytesLeft and OutBytesLeft
 parameters, and increments the InBuf and OutBuf pointers.  If the iconv
 subroutine is unsuccessful, it updates the variables to reflect the extent of
 the  conversion  before  it stopped, and sets errno to one of the following
 values:

 EILSEQ    The conversion has been stopped due to an input byte that does not
           belong to the input codeset.

 E2BIG     The conversion has been stopped due to lack of space in the output
           buffer.

 EINVAL    The conversion has been stopped due to an incomplete character or
           shift sequence at the end of the input buffer.

 EBADF     The argument CD is invalid.

 Related Information

   o  genxlt
   o  iconv_open  - allocates all resources needed by iconv.
   o  iconv_close  - Deallocates all resources allocated by iconv_open.
   o  iconv.h  - Header file for iconv prototypes.

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <string.h>
  #include <wchar.h>
  #include <iconv.h>
  #define  MAX_LEN  255

  int main(void) {
      char *from = "IBM-037",
      char *to   = "IBM-850";

      char buf2[256];
      long i;

      iconv_t cd;

      char *inptr;
      char *outptr;

      size_t inleft;
      size_t outleft;
      size_t ret;

      char line[MAX_LEN] = "THIS IS THE LINE TO CONVERT",
      char result[MAX_LEN];

      buf2[0] = NULL;
      inptr = line;
      inleft = strlen(inptr);
      outleft = sizeof(buf2);
      outptr = buf2;

      printf("Converting from %s to %s.\n",from,to);
      cd = iconv_open(from,to);

      if ((int) cd <= 0) {
        printf("ERROR OPENING ICONV TABLES");
        return 1;
        }

      ret = iconv(cd, &inptr, &inleft, &outptr, &outleft);
      *outptr = NULL;

      printf("original string: %s\n",line);
      printf("modified string: %s\n",buf2);

      iconv_close(cd);
      return(1);
      }

 This program is used to convert all the characters from one character table
 IBM-437 to another IBM-850.  The characters are contained in the variable
 "line".


ΓòÉΓòÉΓòÉ 5.3. ICONV_CLOSE -- Deallocates all resources allocated by iconv_open ΓòÉΓòÉΓòÉ


Syntax

#include <iconv.h>

int iconv_close(iconv_t *cd);

Description

The function iconv_close is used to deallocate all resources that have been
allocated by the iconv_open function including the conversion descriptor that
is specified by the pointer "*cd".
Related Information

   o  iconv  - Converts string of char from one character code set to another.
   o  iconv_open  - allocates all resources needed by iconv.
   o  iconv.h  - Header file for iconv prototypes.

 Example

  See iconv for example.


ΓòÉΓòÉΓòÉ 6. IS* Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6.1. IS* Functions -- Character identification functions ΓòÉΓòÉΓòÉ


Syntax

#include <ctype.h>

int isalnum(int c); /* Tests for: upper or lowercase letters, or decimal digit */
int isalpha(int c); /* Tests for: alphabetic character */
int iscntrl(int c); /* Tests for: any control character */
int isdigit(int c); /* Tests for: decimal digit */
int isgraph(int c); /* Tests for: printable character excluding space */
int islower(int c); /* Tests for: lowercase */
int isprint(int c); /* Tests for: printable character including space */
int ispunct(int c); /* Tests for: any nonalphanumeric printable character */
                                   /* excluding space */
int isspace(int c); /* Tests for: whitespace character */
int isupper(int c); /* Tests for: uppercase */
int isxdigit(int c); /* Tests for: hexadecimal digit */


Description

The <ctype.h> functions listed test a given integer value. They return a
nonzero value if the integer satisfies the test condition, or a zero value if
it does not. EOF is a valid input value.
Related Information

   o  tolower - toupper  - Convert Character Case
   o  ctype.h

 Example

  #include <stdio.h>
  #include <ctype.h>

  #define UPPER_LIMIT   0xFF

  int main(void) {
      int ch;

      for ( ch = 0; ch <= UPPER_LIMIT; ++ch ) {
        printf("\n%3d ", ch);
        printf("%#04x ", ch);
        printf("%3s ", isalnum(ch)  ? "AN" : " ");
        printf("%2s ", isalpha(ch)  ? "A"  : " ");
        printf("%2s",  iscntrl(ch)  ? "C"  : " ");
        printf("%2s",  isdigit(ch)  ? "D"  : " ");
        printf("%2s",  isgraph(ch)  ? "G"  : " ");
        printf("%2s",  islower(ch)  ? "L"  : " ");
        printf(" %c",  isprint(ch)  ? ch   : ' ');
        printf("%3s",  ispunct(ch)  ? "PU" : " ");
        printf("%2s",  isspace(ch)  ? "S"  : " ");
        printf("%3s",  isprint(ch)  ? "PR" : " ");
        printf("%2s",  isupper(ch)  ? "U"  : " ");
        printf("%2s",  isxdigit(ch) ? "X"  : " ");
        }

      }

 This example analyzes all characters between code 0x0 and code UPPER_LIMIT,
 printing A for alphabetic characters, AN for alphanumerics, U for uppercase, L
 for lowercase, D for digits, X for hexadecimal digits, S for spaces, PU for
 punctuation, PR for printable characters, G for graphics characters, and C for
 control characters. This example prints the code if printable.

 The output of this example is a 256-line table showing the characters from 0
 to 255 that possess the attributes tested.


ΓòÉΓòÉΓòÉ 6.2. ISW* -- Character identification functions ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int iswalnum(wint_t wc); /* Tests for: upper/lowercase letters, and digits */
int iswalpha(wint_t wc); /* Tests for: alphabetic character */
int iswcntrl(wint_t wc); /* Tests for: any control character */
int iswdigit(wint_t wc); /* Tests for: decimal digit */
int iswgraph(wint_t wc); /* Tests for: printable character excluding space */
int iswlower(wint_t wc); /* Tests for: lowercase */
int iswprint(wint_t wc); /* Tests for: printable character including space */
int iswpunct(wint_t wc); /* Tests for: any nonalphanumeric printable character */
                                   /* excluding space */
int iswspace(wint_t wc); /* Tests for: whitespace character */
int iswupper(wint_t wc); /* Tests for: uppercase */
int iswxdigit(wint_t wc); /* Tests for: hexadecimal digit */

Description

The <wchar.h> functions listed test a given wide character value. They return a
nonzero value if the wide character satisfies the test condition, or a zero
value if it does not.

wc must be representable as an wide character.  Note:  WEOF is a valid input
value.
Related Information

   o  is* functions
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define UPPER_LIMIT   0xFF

  int main(void) {
      wint_t ch;

      for ( ch = 0; ch <= UPPER_LIMIT; ++ch ) {
        printf("\n%3d ", ch);
        printf("%#04x ", ch);
        printf("%3s ", iswalnum(ch)  ? "AN" : " ");
        printf("%2s ", iswalpha(ch)  ? "A"  : " ");
        printf("%2s",  iswcntrl(ch)  ? "C"  : " ");
        printf("%2s",  iswdigit(ch)  ? "D"  : " ");
        printf("%2s",  iswgraph(ch)  ? "G"  : " ");
        printf("%2s",  iswlower(ch)  ? "L"  : " ");
        printf(" %c",  iswprint(ch)  ? ch   : ' ');
        printf("%3s",  iswpunct(ch)  ? "PU" : " ");
        printf("%2s",  iswspace(ch)  ? "S"  : " ");
        printf("%3s",  iswprint(ch)  ? "PR" : " ");
        printf("%2s",  iswupper(ch)  ? "U"  : " ");
        printf("%2s",  iswxdigit(ch) ? "X"  : " ");
        }

      }

 This example analyzes all characters between code 0x0 and code UPPER_LIMIT,
 printing A for alphabetic characters, AN for alphanumerics, U for uppercase, L
 for lowercase, D for digits, X for hexadecimal digits, S for spaces, PU for
 punctuation, PR for printable characters, G for graphics characters, and C for
 control characters. This example prints the code if printable.

 The output of this example is a 256-line table showing the characters from 0
 to 255 that possess the attributes tested.


ΓòÉΓòÉΓòÉ 6.3. ISWCTYPE -- Class test for characters ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int iswctype(wint_t wc, wctype_t mask);

Description

The iswctype functions uses the character class to determine if a wide
character is in a specific class.  The character classes are defined in each
locale by the following key strings:

 "alnum"    -  for the alpha numeric class.

 "alpha"    -  for the alphabetic only class.

 "cntrl"    -  for the control class.

 "digit"    -  for the digit class.

 "graph"    -  for the graphics character class.

 "lower"    -  for the lower case character class.

 "print"    -  for the printable character class.

 "punct"    -  for the punctuation class.

 "space"    -  for the space character class.

 "upper"    -  for the upper case character class.

 "xdigit"   -  for the digit or alpha character class.

 "blank"    -  for the hexadecimal alpha numeric class.

 Related Information

   o  wctype
   o  wchar.h
   o  isw* functions

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define UPPER_LIMIT   0xFF

  int main(void) {
      wint_t ch;

      for ( ch = 0; ch <= UPPER_LIMIT; ++ch ) {
        printf("\n%3d ", ch);
        printf("%#04x ", ch);
        printf("%3s ", iswctype(ch,wctype("alnum"))  ? "AN" : " ");
        printf("%2s ", iswctype(ch,wctype("alpha"))  ? "A"  : " ");
        printf("%2s", iswctype(ch,wctype("cntrl"))  ? "C"  : " ");
        printf("%2s", iswctype(ch,wctype("digit"))  ? "D"  : " ");
        printf("%2s", iswctype(ch,wctype("graph"))  ? "G"  : " ");
        printf("%2s", iswctype(ch,wctype("lower"))  ? "L"  : " ");
        printf(" %c", iswctype(ch,wctype("blank"))  ? "B"  : " ");
        printf("%3s", iswctype(ch,wctype("punct"))  ? "PU" : " ");
        printf("%2s", iswctype(ch,wctype("space"))  ? "S"  : " ");
        printf("%3s", iswctype(ch,wctype("print"))  ? "PR" : " ");
        printf("%2s", iswctype(ch,wctype("upper"))  ? "U"  : " ");
        printf("%2s", iswctype(ch,wctype("xdigit")) ? "X"  : " ");
        }

      }

 This example analyzes all characters between code 0x0 and code UPPER_LIMIT,
 printing A for alphabetic characters, AN for alphanumerics, U for uppercase, L
 for lowercase, D for digits, X for hexadecimal digits, S for spaces, PU for
 punctuation, PR for printable characters, G for graphics characters, and C for
 control characters. This example prints the code if printable.

 The output of this example is a 256-line table showing the characters from 0
 to 255 that possess the attributes tested.


ΓòÉΓòÉΓòÉ 6.4. TOLOWER / TOUPPER -- Convert character case ΓòÉΓòÉΓòÉ


Syntax

#include <ctype.h>

int tolower(int c);   /* Convert c to lowercase if appropriate */

int toupper(int c);   /* Convert c to uppercase if appropriate */

Description

The tolower function returns a lowercase c if c represents an uppercase letter;
otherwise, c is returned.  c is unchanged.

The toupper function returns an uppercase c if c represents a lowercase letter;
otherwise, c is returned. c is unchanged.
Related Information

   o  isalnum to isxdigit  - Test Integer Value
   o  isascii - Test Integer Values
   o  toascii - Convert Character
   o  tolower - Convert Character
   o  toupper - Convert Character
   o  wchar.h

 Example

  #include <stdio.h>
  #include <ctype.h>

  int main(void) {
      int ch;

      for (ch = 0; ch <= 0x7f; ch++) {
        printf("\ntoupper=%#04x  -  ", toupper(ch));
        printf("tolower=%#04x", tolower(ch));
        }

      }

 This example uses the toupper and tolower functions to modify characters
 between code 0 and code 7f.


ΓòÉΓòÉΓòÉ 7. Locale/MB* Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.1. LOCALECONV -- Defines values for lconv structure based on Locale ΓòÉΓòÉΓòÉ


Syntax

#include <locale.h>
#include <wchar.h>

struct lconv *localeconv(void);

Description

The localeconv function sets the components of a structure having type struct
lconv to values appropriate for the current locale.  The structure may be
overwritten by another call to localeconv or by calling setlocale and passing
LC_ALL, LC_MONETARY, or LC_NUMERIC.

The structure contains the following elements (defaults shown are for the C
locale):

ELEMENT                    PURPOSE OF ELEMENT                DEFAULT

            "char *decimal_point"     Radix character                   "."
                                      used to format non-monetary
                                      quantities.

            "char *thousands_sep"     Character used to separate        ""
                                      groups of digits to the
                                      left of the decimal-point
                                      character in formatted
                                      nonmonetary quantities.

            "char *grouping"          String whose elements taken       ""
                                      as one-byte integer values
                                      indicate the size of each
                                      group of digits in formatted
                                      non-monetary quantities.

            "char *int_curr_symbol"   International currency            ""
                                      symbol for the current
                                      locale.  The first three
                                      characters contain the
                                      alphabetic international
                                      currency symbol.  The
                                      fourth character (usually
                                      a space) is the character
                                      used to separate the
                                      international currency
                                      symbol from the monetary
                                      quantity.

            "char *currency_symbol"   Local currency symbol of          ""
                                      the current locale.

            "char *mon-decimal_point" Radix character                   "."
                                      used to format monetary
                                      quantities.

            "char *mon_thousands_sep" Separator for digits in           ""
                                      formatted monetary quantities.

            "char *mon_grouping"      String whose elements taken       ""
                                      as one-byte integer values
                                      indicate the size of each
                                      group of digits in formatted
                                      monetary quantities.

            "char *positive_sign"     String indicating a positive
                                      value formatted monetary
                                      quantity.

            "char *negative_sign"     String indicating a negative
                                      value formatted monetary
                                      quantity.

            "char int_frac_digits"    The number of displayed digits    "UCHAR_MAX"
                                      to the right of the decimal
                                      place for internationally
                                      formatted monetary quantities.

            "char frac_digits"        Number of digits to the           "UCHAR_MAX"
                                      right of the decimal place
                                      in monetary quantities.

            "char p_cs_precedes"      1 if the "currency_symbol" or     "UCHAR_MAX"
                                      int_curr_symbol precedes the
                                      value for a non-negative
                                      formatted monetary quantity;
                                      0 if it succedes the value.

            "char p_sep_by_space"     0 if the "currency_symbol" or     "UCHAR_MAX"
                                      int_curr_symbol is not
                                      separated by a from the
                                      value for a non-negative
                                      formatted space monetary
                                      quantity;
                                      1 if a space separates the
                                      symbol from the value; and
                                      2 if a space separates the
                                      symbol and the sign string,
                                      if adjacent.

            "char n_cs_precedes"      1 if the "currency_symbol" or     "UCHAR_MAX"
                                      int_curr_symbol precedes the
                                      value for a negative
                                      formatted monetary quantity;
                                      0 if it succedes the value.

            "char n_sep_by_space"     0 if the "currency_symbol" or     "UCHAR_MAX"
                                      int_curr_symbol is not
                                      separated by a space from the
                                      value for a negative formatted
                                      monetary quantity;  1 if a
                                      space separates the symbol
                                      from the value; and 2 if a
                                      space separates the symbol
                                      and the sign string,
                                      if adjacent.

            "char p_sign_posn"        Value indicating the position
                                      of the "positive_sign" for a
                                      non-negative formatted
                                      monetary quantity.

            "char n_sign_posn"        Value indicating the position of
                                      the "negative_sign" for a negative
                                      formatted monetary quantity.

 The n_sign_posn and p_sign_posn elements can have the following values:

  Value Meaning
  0  Parentheses surround the quantity and currency_symbol or int_curr_symbol.
  1  The sign precedes the quantity and currency_symbol or int_curr_symbol.
  2  The sign follows the quantity and currency_symbol or int_curr_symbol.
  3  The sign precedes the currency_symbol or int_curr_symbol.
  4  The sign follows the currency_symbol or int_curr_symbol.

 The localeconv function returns a pointer to the structure.
 Related Information

   o  setlocale  - Set Locale
   o  locale.h

 Example

  #include <stdio.h>
  #include <wchar.h>
  #include <locale.h>

  int main(void) {
      char * string;
      struct lconv * mylocale;
      mylocale = localeconv();
      /* Default decimal point */
      printf( "Default decimal point is a %s\n",
           mylocale->decimal_point );

      string = setlocale(LC_ALL,"Fr_FR");
      mylocale = localeconv();

      /*****************************************
      * A comma is set to be the decimal point *
      * when the locale is LC_FRANCE           *
      *****************************************/

      printf( "France's decimal point is a %s\n", mylocale->decimal_point );
      }

  /****************  Output should be similar to:  ******************

  Default decimal point is a .
  France's decimal point is a ,

  *******************************************************************/

 This example prints out the default decimal point for your locale and then the
 decimal point for the LC_FRANCE locale.


ΓòÉΓòÉΓòÉ 7.2. MBLEN -- Length in bytes of multi-byte character ΓòÉΓòÉΓòÉ


Syntax

#include <stdlib.h>
#include <wchar.h>

int mblen(const char *string, size_t n);

Description

The mblen function determines the length in bytes of the multi-byte character
pointed to by string. A maximum of n bytes is examined.

If string is NULL, the mblen function returns:

   o  Nonzero when encodings have state dependency

   o  Zero otherwise.

 If string is not NULL, the mblen function returns:

   o  Zero if string points to the null character

   o  The number of bytes comprising the multi-byte character

   o  -1 if string does not point to a valid multi-byte character.

 Related Information

   o  mbtowc  - Convert multi-byte character to wchar_t
   o  mbstowcs  - Convert multi-byte characters to wchar_t characters
   o  strlen   - Determine string length
   o  wcslen  - Calculate length of wchar_t string
   o  wctomb  - Convert wchar_t character to multi-byte character
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      int   length;
      char *string = "String of multi byte characters";

      length = mblen(string, MB_CUR_MAX);

      printf("mblen rc %i  multi-byte character: %c",length,*string);
      }

 This example uses mblen to obtain the length of a multi-byte string.


ΓòÉΓòÉΓòÉ 7.3. MBSTOWCS -- Converts multi-byte strings to wide-character strings ΓòÉΓòÉΓòÉ


Syntax

#include <stdlib.h>
#include <wchar.h>

size_t mbstowcs(wchar_t *pwc, const char *string, size_t n);

Description

The mbstowcs function converts a string of multi-byte characters into a string
of wide-characters. No more than n characters will be converted.

The mbstowcs function returns the number of wchar_t characters generated not
including any terminating zero codes.  If a multi-byte character that is not
valid is encountered, the function returns -1.
Related Information

   o  mblen  - Multi-byte string length
   o  mbtowc  - Convert multi-byte character to wchar_t
   o  wcslen  - Calculate length of wchar_t string
   o  wcstombs  - Convert wchar_t string to multi-byte character string
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      int     rc;
      char   *string = "String of multi byte characters";
      wchar_t arr[20];

      rc = mbstowcs(arr,string,19);

      printf("\n\nmbstowcs rc %i   wide-character string: %S\n",rc,&arr[0]);
      }

 This example uses mbstowcs to convert a multi-byte character string into a
 wide-character string.


ΓòÉΓòÉΓòÉ 7.4. MBTOWC -- Converts multi-byte character to wide-character ΓòÉΓòÉΓòÉ


Syntax

#include <stdlib.h>
#include <wchar.h>

int mbtowc(wchar_t *pwc, const char *string, size_t n);

Description

The mbtowc function first determines the length of the multi-byte character
pointed to by string.  It then stores the code for the multi-byte character in
the wchar_t object pointed to by pwc.  A maximum of n bytes is examined.

If string is NULL, the mbtowc function returns:

   o  Nonzero when encodings have state dependency

   o  0 otherwise.

 If string is not NULL, the mbtowc function returns:

   o  0 if string points to the null character

   o  The number of bytes comprising the converted multi-byte character

   o  -1 if string does not point to a valid multi-byte character.

 Related Information

   o  mblen  - Multi-byte string length
   o  mbstowcs  - Convert multi-byte characters to wchar_t characters
   o  wcslen  - Calculate length of wchar_t string
   o  wctomb  - Convert wchar_t character to multi-byte character
   o  wchar.h

 Example

  #include <stdio.h>
  #include <stdlib.h>
  #include <wchar_t.h>

  int main(void) {
      int     rc;
      char   *string = "ABC";
      wchar_t arr;

      rc = mbtowc(&arr,string,MB_CUR_MAX);

      printf("\nmbtowc rc : %i   wide-character : %C\n",rc,arr);
      }

 This example uses mbtowc to convert a multi-byte character into a single
 wide-character.


ΓòÉΓòÉΓòÉ 7.5. NL_LANGINFO -- Retrieves information about data defined in Locale ΓòÉΓòÉΓòÉ


Syntax

#include <langinfo.h>

char *nl_langinfo(nl_item item);

Description

The function nl_langinfo returns a character pointer to a string that contains
information about the parameter "item" that is supplied by the country's
locale.  The values for "item" are defined in the file langinfo.h.
Related Information

   o  langinfo.h

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <langinfo.h>
  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      printf("\nCalling setlocale\n");
      printf("Setlocale returns: %s \n", setlocale(LC_ALL, ""));

      printf("My Kingdom for a Day and a Month : %s %s",
      nl_langinfo(DAY_5),nl_langinfo(ABMON_10));

      return(1);
      }

 This program queries the current locale for the string which defines the
 parameter DAY_5 and ABMON_10.


ΓòÉΓòÉΓòÉ 7.6. WCSTOMBS -- Converts a wide-character string to a multi-byte string ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

size_t wcstombs(char *dest, const wchar_t *ws, size_t count);

Description.

The wcstombs function converts the wchar_t string pointed to by ws into the
multi-byte array pointed to by dest. The converted string begins in the initial
shift state. The conversion stops after count bytes in dest are filled up or a
wchar_t null character is encountered.

The wcstombs function returns the length in bytes of the multi-byte character
string, not including a terminating null character. The value -1 is returned if
an invalid multi-byte character is encountered.
Related Information

   o  mbstowcs  - Convert multi-byte Characters to wchar_t Characters
   o  wcslen  - Calculate Length of wchar_t String
   o  wctomb  - Convert wchar_t Character to multi-byte Character
   o  wchar.h

 Example

  #include <stdio.h>
  #include <stdlib.h>
  #include <string.h>
  #include <wchar.h>

  int main(void) {
      char dest[20];
      wchar_t dptr[20];
      size_t count = 20;
      size_t length;

      mbstowcs(dptr,"string",7);
      length = wcstombs( dest, dptr, count );
      printf( "%d bytes were converted.\n", length );
      printf( "The converted string is \"%s\"\n\n", dest );

      memset( dest, '\0', sizeof(dest));      /* Initialize the buffer */

      /* Now convert only 3 bytes */
      length = wcstombs( dest, dptr, 3 );

      printf( "%d bytes were converted.\n", length );
      printf( "The converted string is \"%s\"\n", dest );
      }
  /****************  Output should be similar to:  ******************

  12 bytes were converted.
  The converted string is "string"

  3 bytes were converted.
  The converted string is "str"

  *******************************************************************/

 In this example, a wchar_t string is converted to a char string twice. The
 first call converts the entire string, while the second call only converts
 three characters. The results are printed each time.


ΓòÉΓòÉΓòÉ 7.7. WCTOMB -- Convert wide character to multibyte character ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int wctomb(char *string, wchar_t character);

Description.

The wctomb function converts the wchar_t value of character into a multibyte
array pointed to by string.  If the value of character is 0, the function is
left in the initial shift state.  At most, wctomb stores MB_CUR_MAX characters
in string.

The wctomb function returns the length in bytes of the multibyte character.
The value -1 is returned if character is not a valid multibyte character.  If
string is a NULL pointer, the wctomb function returns nonzero if
shift-dependent encoding is used, or 0 otherwise.
Related Information

   o  mbtowc  - Convert Multibyte Character to wchar_t.
   o  wcslen  - Calculate Length of wchar_t String.
   o  wcstombs  - Convert wchar_t String to Multibyte Character String.
   o  wchar.h - Header file for wide charcter prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define SIZE 40

  int main(void) {
      static char  buffer[ SIZE ];
      wchar_t wch = 'c';
      int length;

      length = wctomb( buffer, wch );

      printf( "\nThis multibyte character is (%d) byte(s) long", length);
      printf( "And the converted string is \"%s\"\n", buffer );
      }


  /****************  Output should be similar to:  ******************

  This multibyte character is 1 byte(s) long
  And the converted string is "c"

  *******************************************************************/

 This example converts the wide character c to a character.


ΓòÉΓòÉΓòÉ 8. Formatted I/O Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.1. FPRINTF -- Formats output to an output stream ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>

int fprintf(FILE *stream, const char *format-string, argument-list);

Description

The fprintf function formats and writes a series of characters and values to
the output stream.  The fprintf function converts each entry in argument-list,
if any, and writes to the stream according to the corresponding format
specification in the format-string.

The format-string has the same form and function as the format-string argument
for the printf function.

In extended mode, fprintf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

The fprintf function returns the number of characters printed or a negative
value if an output error occurs.
Related Information

   o  fscanf  - Read Formatted Data.
   o  printf  - Formatted Print.
   o  sprintf  - Formatted Print to Buffer.
   o  stdio.h  - Include file for standard I/O functions.

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define MAXLEN  80

  int main(void) {
      int count;
      FILE *stream;
      long l;
      float fp;
      wchar_t s[MAXLEN];
      wchar_t c[MAXLEN];

      fp = 1.34e-2;

      l = 1000000;

      mbstowcs(s,"ABCDEFGHIJKLMNOPQRSTUVWXYZ",MAXLEN);
      mbstowcs(c,"A",MAXLEN);

      stream = fopen("myfile.dat", "w");

      fprintf(stream, "%S", s);
      fprintf(stream, "%ld", l);
      fprintf(stream, "%C", c[0]);
      fprintf(stream, "%f", fp);

      printf("\n");

      fclose(stream);
      }

 This example stores a series of data types to a file "myfile.dat" using the
 fprintf function.


ΓòÉΓòÉΓòÉ 8.2. FSCANF -- Reads data from a stream and returns data to argument list ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h> /* when using C set 2 the header file is <wchar.h> */

int fscanf (FILE *stream, const char *format-string, argument-list);

Description

The fscanf function reads data from the current position of the specified
stream into the locations given by the entries in argument-list, if any.  Each
entry in argument-list must be a pointer to a variable with a type that
corresponds to a type specifier in format-string.

The format-string controls the interpretation of the input fields and has the
same form and function as the format-string argument for the scanf function.
See scanf for a description of format-string.

In extended mode, the fscanf function also reads in the strings "INFINITY",
"INF", and "NAN" (in upper or lowercase) and converts them to the corresponding
floating-point value.  The sign of the value is determined by the format
specification. See Infinity and NaN Support for more information on infinity
and NaN values.

The fscanf function returns the number of fields that it successfully converted
and assigned.  The return value does not include fields that fscanf read but
did not assign.

The return value is ether an EOF if an input failure occurs before any
conversion, or the number of input items assigned successfully converted.  If
EOF is returned then errno maybe checked for additional information.

New Formatting Codes.  Using the n$ feature the order of arguments referenced
can be changed. For example in the following statment: fscanf(stream,"%d
%d",&value1, &value2);  By using the n$ format the value2 could be referenced
before value1.  For example: fscanf(stream,"%2$d %1$d",&value1,&value2).  The
%S is used to print wide character strings for wide character support.  The %C
is used to print individual wide characters for wide character support.
Related Information

   o  fprintf  - Write Formatted Data
   o  scanf  - Read Data
   o  stdio.h  - Normal location for fscanf function prototype,
      however for this implementation uses wchar.h.
   o  wchar.h  - Header file for wide character support.

 Example

  #include <stdio.h>
  #include <stdlib.h>
  #include <wchar.h>

  #define MAXLEN  80

  int main(void) {
      int count;
      FILE *stream;
      long l;
      float fp;
      wchar_t s[MAXLEN];
      wchar_t c;

      for(count=0;count<MAXLEN;count++){s[count]=0;};

      stream = fopen("myfile.dat", "r");

      fscanf(stream, "%26C", &s);
      fscanf(stream, "%ld", &l);
      fscanf(stream, "%C", &c);
      fscanf(stream, "%f", &fp);

      printf("string = %S\n", s);
      printf("long double = %ld\n", l);
      printf("char = %C\n", c);
      printf("float = %f\n", fp);

      printf("\n");

      fclose(stream);
      }


  /***************  If myfile.dat contains  ********************

           ABCDEFGHIJKLMNOPQRSTUVWXYZ1000000A0.013400

  *******************  expected output is:  ********************

  string = ABCDEFGHIJKLMNOPQRSTUVWXYZ
  long double = 1000000
  char = A
  float = 0.013400

  **************************************************************/

 This example opens the file myfile.dat for reading and then scans this file
 for a string, a long integer value, a character, and a floating-point value.


ΓòÉΓòÉΓòÉ 8.3. PRINTF -- Format and print characters ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>

int printf(const char *format-string, ...);

Description

The printf function formats and prints a series of characters and values to the
standard output stream stdout.  The format-string consists of ordinary
characters, escape sequences, and format specifications.  The ordinary
characters are copied in order of their appearance to stdout.  Format
specifications, beginning with a percent sign (%), determine the output format
for any argument-list following the format-string.  The format-string is a
multibyte character string beginning and ending in its initial shift state.

The format-string is read left to right.  When the first format specification
is found, the value of the first argument after the format-string is converted
and output according to the format specification.  The second format
specification causes the second argument after the format-string to be
converted and output, and so on through the end of the format-string.  If there
are more arguments than there are format specifications, the extra arguments
are evaluated and ignored.  The results are undefined if there are not enough
arguments for all the format specifications.  A format specification has the
following form:



 ΓöÇΓöÇ%ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇtypeΓöÇΓöÇ
        Γöé         Γöé  Γöé         Γöé  Γöé                Γöé  Γöé     Γöé
        ΓööΓöÇΓöÇflagsΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇwidthΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇ.ΓöÇΓöÇprecisionΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇhΓöÇΓöÇΓöñ
                                                      Γöé     Γöé
                                                      Γö£ΓöÇΓöÇLΓöÇΓöÇΓöñ
                                                      Γöé     Γöé
                                                      ΓööΓöÇΓöÇlΓöÇΓöÇΓöÿ

Each field of the format specification is a single character or number
signifying a particular format option.  The type character, which appears after
the last optional format field, determines whether the associated argument is
interpreted as a character, a string, a number, or pointer.  The simplest
format specification contains only the percent sign and a type character (for
example, %s).

The following optional fields control other aspects of the formatting:

Field       Description

flags       Justification of output and printing of signs, blanks,
            decimal points, octal, and hexadecimal prefixes, and the
            semantics for wchar_t precision unit.

width       Minimum number of characters (bytes) output.

precision   Maximum number of characters (bytes) printed for all or
            part of the output field, or minimum number of digits
            printed for integer values.

h,l,L       Size of argument expected.

The type characters and their meanings are given in the following table:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CHAR- Γöé ARGUMENT   Γöé OUTPUT FORMAT                             Γöé
Γöé ACTER Γöé            Γöé                                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé d, i  Γöé Integer    Γöé Signed decimal integer.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé u     Γöé Integer    Γöé Unsigned decimal integer.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé o     Γöé Integer    Γöé Unsigned octal integer.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé x     Γöé Integer    Γöé Unsigned hexadecimal integer, using       Γöé
Γöé       Γöé            Γöé abcdef.                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé X     Γöé Integer    Γöé Unsigned hexadecimal integer, using       Γöé
Γöé       Γöé            Γöé ABCDEF.                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé f     Γöé Double     Γöé Signed value having the form              Γöé
Γöé       Γöé            Γöé [-]dddd.dddd, where dddd is one or more   Γöé
Γöé       Γöé            Γöé decimal digits.  The number of digits     Γöé
Γöé       Γöé            Γöé before the decimal point depends on the   Γöé
Γöé       Γöé            Γöé magnitude of the number.  The number of   Γöé
Γöé       Γöé            Γöé digits after the decimal point is equal   Γöé
Γöé       Γöé            Γöé to the requested precision.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé e     Γöé Double     Γöé Signed value having the form              Γöé
Γöé       Γöé            Γöé [-]d.dddd"e"[sign]ddd, where d is a       Γöé
Γöé       Γöé            Γöé single-decimal digit, dddd is one or more Γöé
Γöé       Γöé            Γöé decimal digits, ddd is 2 or more decimal  Γöé
Γöé       Γöé            Γöé digits, and sign is + or -.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé E     Γöé Double     Γöé Identical to the "e" format except that   Γöé
Γöé       Γöé            Γöé "E" introduces the exponent instead of    Γöé
Γöé       Γöé            Γöé "e".                                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé g     Γöé Double     Γöé Signed value printed in "f" or "e"        Γöé
Γöé       Γöé            Γöé format.  The "e" format is used only when Γöé
Γöé       Γöé            Γöé the exponent of the value is less than -4 Γöé
Γöé       Γöé            Γöé or greater than precision.  Trailing      Γöé
Γöé       Γöé            Γöé zeros are truncated, and the decimal      Γöé
Γöé       Γöé            Γöé point appears only if one or more digits  Γöé
Γöé       Γöé            Γöé follow it.                                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé G     Γöé Double     Γöé Identical to the "g" format except that   Γöé
Γöé       Γöé            Γöé "E" introduces the exponent (where appro- Γöé
Γöé       Γöé            Γöé priate) instead of "e".                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé c     Γöé Character  Γöé Single character.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé s     Γöé String     Γöé Characters printed up to the first null   Γöé
Γöé       Γöé            Γöé character (\"0") or until precision is    Γöé
Γöé       Γöé            Γöé reached.                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé n     Γöé Pointer to Γöé Number of characters successfully written Γöé
Γöé       Γöé integer    Γöé so far to the stream or buffer; this      Γöé
Γöé       Γöé            Γöé value is stored in the integer whose      Γöé
Γöé       Γöé            Γöé address is given as the argument.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé p     Γöé Pointer    Γöé Pointer to void converted to a sequence   Γöé
Γöé       Γöé            Γöé of printable characters.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "lc"  Γöé Wide char- Γöé Multibyte character.                      Γöé
Γöé       Γöé acter      Γöé                                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "ls"  Γöé Wide       Γöé Multibyte characters printed up to the    Γöé
Γöé       Γöé string     Γöé first "wchar_t" null character ("L\0") or Γöé
Γöé       Γöé            Γöé until precision is reached.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé C     Γöé Wide char- Γöé A wchar_t character is converted into an  Γöé
Γöé       Γöé acter to   Γöé array of characters representing an multi Γöé
Γöé       Γöé Multibyte  Γöé byte character and this character is      Γöé
Γöé       Γöé            Γöé printed out.  Same result as wctomb().    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé S     Γöé Wide char- Γöé Takes a pointer to an array of wchar_t    Γöé
Γöé       Γöé acter str- Γöé characters and converts it to an array of Γöé
Γöé       Γöé ing to     Γöé multibyte characters upto but not         Γöé
Γöé       Γöé Multibyte  Γöé including the null character and prints   Γöé
Γöé       Γöé String     Γöé the result.  Same result as wcstombs().   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The flag characters and their meanings are as follows (notice that more than
one flag can appear in a format specification):

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé FLAG      Γöé MEANING                     Γöé DEFAULT              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé -         Γöé Left-justify the result     Γöé Right-justify.       Γöé
Γöé           Γöé within the field width.     Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé +         Γöé Prefix the output value     Γöé Sign appears only    Γöé
Γöé           Γöé with a sign (+ or -) if the Γöé for negative signed  Γöé
Γöé           Γöé output value is of a signed Γöé values (-).          Γöé
Γöé           Γöé type.                       Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé blank(' ')Γöé Prefix the output value     Γöé No blank.            Γöé
Γöé           Γöé with a blank if the output  Γöé                      Γöé
Γöé           Γöé value is signed and posi-   Γöé                      Γöé
Γöé           Γöé tive.  The "+" flag over-   Γöé                      Γöé
Γöé           Γöé rides the blank flag if     Γöé                      Γöé
Γöé           Γöé both appear, and a positive Γöé                      Γöé
Γöé           Γöé signed value will be output Γöé                      Γöé
Γöé           Γöé with a sign.                Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé #         Γöé When used with the "o",     Γöé No prefix.           Γöé
Γöé           Γöé "x", or "X" formats, the    Γöé                      Γöé
Γöé           Γöé "#" flag prefixes any       Γöé                      Γöé
Γöé           Γöé nonzero output value with   Γöé                      Γöé
Γöé           Γöé "0", "0"x, or "0"X, respec- Γöé                      Γöé
Γöé           Γöé tively.                     Γöé                      Γöé
Γöé           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé           Γöé When used with the "f",     Γöé Decimal point        Γöé
Γöé           Γöé "e", or "E" formats, the    Γöé appears only if      Γöé
Γöé           Γöé "#" flag forces the output  Γöé digits follow it.    Γöé
Γöé           Γöé value to contain a decimal  Γöé                      Γöé
Γöé           Γöé point in all cases.         Γöé                      Γöé
Γöé           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé           Γöé When used with the "g" or   Γöé Decimal point        Γöé
Γöé           Γöé "G" formats, the "#" flag   Γöé appears only if      Γöé
Γöé           Γöé forces the output value to  Γöé digits follow it;    Γöé
Γöé           Γöé contain a decimal point in  Γöé trailing zeros are   Γöé
Γöé           Γöé all cases and prevents the  Γöé truncated.           Γöé
Γöé           Γöé truncation of trailing      Γöé                      Γöé
Γöé           Γöé zeros.                      Γöé                      Γöé
Γöé           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé           Γöé When used with the "ls"     Γöé Precision indicates  Γöé
Γöé           Γöé format, the "#" flag causes Γöé the maximum number   Γöé
Γöé           Γöé precision to be measured in Γöé of bytes to be       Γöé
Γöé           Γöé "wchar_t" characters.       Γöé output.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "0"       Γöé When used with the "d",     Γöé Space padding.       Γöé
Γöé           Γöé "i", "o", "u", "x", "X",    Γöé                      Γöé
Γöé           Γöé "e", "E", "f", "g", or "G"  Γöé                      Γöé
Γöé           Γöé formats, the "0" flag       Γöé                      Γöé
Γöé           Γöé causes leading "0"'s to pad Γöé                      Γöé
Γöé           Γöé the output to the field     Γöé                      Γöé
Γöé           Γöé width.  The "0" flag is     Γöé                      Γöé
Γöé           Γöé ignored if precision is     Γöé                      Γöé
Γöé           Γöé specified for an integer or Γöé                      Γöé
Γöé           Γöé if the "-" flag is speci-   Γöé                      Γöé
Γöé           Γöé fied.                       Γöé                      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The # flag should not be used with c, lc, d, i, u, s, or p types.

Width is a nonnegative decimal integer controlling the minimum number of
characters printed.  If the number of characters in the output value is less
than the specified width, blanks are added on the left or the right (depending
on whether the - flag is specified) until the minimum width is reached.

Width never causes a value to be truncated;  if the number of characters in the
output value is greater than the specified width, or width is not given, all
characters of the value are printed ( subject to the precision specification).

For the ls type, width is specified in bytes. If the number of bytes in the
output value is less than the specified width, single-byte blanks are added on
the left or the right (depending on whether the - flag is specified) until the
minimum width is reached.

The width specification can be an asterisk (*), in which case an argument from
the argument list supplies the value.  The width argument must precede the
value being formatted in the argument list.

Precision is a nonnegative decimal integer preceded by a period, which
specifies the number of characters to be printed or the number of decimal
places.  Unlike the width specification, the precision can cause truncation of
the output value or rounding of a floating-point value.

The precision specification can be an asterisk (*), in which case an argument
from the argument list supplies the value.  The precision argument must precede
the value being formatted in the argument list.

The interpretation of the precision value and the default when the precision is
omitted depend upon the type, as shown in the following table:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé TYPE  Γöé MEANING                         Γöé DEFAULT              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    i  Γöé Precision specifies the minimum Γöé If precision is "0"  Γöé
Γöé    d  Γöé number of digits to be printed. Γöé or omitted entirely, Γöé
Γöé    u  Γöé If the number of digits in the  Γöé or if the period (.) Γöé
Γöé    o  Γöé argument is less than           Γöé appears without a    Γöé
Γöé    x  Γöé precision, the output value is  Γöé number following it, Γöé
Γöé    X  Γöé padded on the left with zeros.  Γöé the precision is set Γöé
Γöé       Γöé The value is not truncated when Γöé to 1.                Γöé
Γöé       Γöé the number of digits exceeds    Γöé                      Γöé
Γöé       Γöé precision.                      Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    f  Γöé Precision specifies the number  Γöé Default precision is Γöé
Γöé    e  Γöé of digits to be printed after   Γöé six.  If precision   Γöé
Γöé    E  Γöé the decimal point.  The last    Γöé is "0" or the period Γöé
Γöé       Γöé digit printed is rounded.       Γöé appears without a    Γöé
Γöé       Γöé                                 Γöé number following it, Γöé
Γöé       Γöé                                 Γöé no decimal point is  Γöé
Γöé       Γöé                                 Γöé printed.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    g  Γöé Precision specifies the maximum Γöé All significant      Γöé
Γöé    G  Γöé number of significant digits    Γöé digits are printed.  Γöé
Γöé       Γöé printed.                        Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    c  Γöé No effect.                      Γöé The character is     Γöé
Γöé       Γöé                                 Γöé printed.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    lc Γöé No effect.                      Γöé The "wchar_t" char-  Γöé
Γöé       Γöé                                 Γöé acter is printed.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    s  Γöé Precision specifies the maximum Γöé Characters are       Γöé
Γöé       Γöé number of characters to be      Γöé printed until a null Γöé
Γöé       Γöé printed.  Characters in excess  Γöé character is         Γöé
Γöé       Γöé of precision are not printed.   Γöé encountered.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé    ls Γöé Precision specifies the maximum Γöé "wchar_t" characters Γöé
Γöé       Γöé number of bytes to be printed.  Γöé are printed until a  Γöé
Γöé       Γöé Bytes in excess of precision    Γöé null character is    Γöé
Γöé       Γöé are not printed; however,       Γöé encountered.         Γöé
Γöé       Γöé multibyte integrity is always   Γöé                      Γöé
Γöé       Γöé preserved.                      Γöé                      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The h, l, and L characters specify the size of the expected argument.  Their
meanings are as follows: h   A prefix with the integer types d, i, o, u, x, X,
and n    that specifies that the argument is short int or    unsigned short
int.  l   A prefix with d, i, o, u, x, X, and n types that    specifies that
the argument is a long int or    unsigned long int.  L   A prefix with e, E, f,
g, or G types that specifies that    the argument is long double.

If a percent sign (%) is followed by a character that has no meaning as a
format field, the character is simply copied to stdout.  For example, to print
a percent sign character, use %%.

The printf function returns the number of characters (bytes) printed.
Related Information

   o  fprintf  - Write Formatted Data
   o  fscanf  - Read Formatted Data
   o  scanf  - Read Data
   o  sprintf  - Formatted Print to Buffer
   o  sscanf  - Read Data
   o  stdio.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      char ch = 'h', *string = "computer";
      int count = 234, hex = 0x10, oct = 010, dec = 10;
      double fp = 251.7366;
      wchar_t wc = (wchar_t)0x0058;
      wchar_t ws[4];

      ws[0] = (wchar_t)0x0041;
      ws[1] = (wchar_t)0x0042;
      ws[2] = (wchar_t)0x0043;
      ws[3] = (wchar_t)0x0000;

      printf("%d   %+d    %06d     %X    %x     %o\n\n",
          count, count, count, count, count, count);

      printf("1234567890123%n4567890123456789\n\n", &count);
      printf("Value of count should be 13; count = %d\n\n", count);
      printf("%10c%5c\n", ch, ch);
      printf("%25s\n%25.4s\n\n", string, string);
      printf("%f    %.2f    %e    %E\n\n", fp, fp, fp, fp);
      printf("%i    %i     %i\n\n", hex, oct, dec);
      printf("%C    %S\n\n",wc,ws);
      printf("%2$C    %1$2S\n\n",ws,wc);
      }

  /*****************  Output should be similar to:  *****************

  234   +234    000234     EA    ea     352

  12345678901234567890123456789

  Value of count should be 13; count = 13

    h    h
            computer
                comp

  251.736600    251.74    2.517366e+02    2.517366E+02

  16    8     10

  X     ABC

  X     AB

  *******************************************************************/

 This example prints data in a variety of formats.


ΓòÉΓòÉΓòÉ 8.4. SCANF -- Reads formatted data from the standard input ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>

int scanf(const char *format-string, argument-list);

Description

The scanf function reads data from the standard input stream stdin into the
locations given by each entry in argument-list. Each argument must be a pointer
to a variable with a type that corresponds to a type specifier in
format-string.  The format-string controls the interpretation of the input
fields, and is a multibyte character string beginning and ending in its initial
shift state.

The format-string can contain one or more of the following:

   o  White-space characters, as specified by isspace (such as blanks and
      new-line characters). A white-space character causes scanf to read, but
      not to store, all consecutive white-space characters in the input up to
      the next character that is not white-space.  One white-space character in
      format-string matches any combination of white-space characters in the
      input.

   o  Characters that are not white space, except for the percent sign
      character (%).  A non-white-space character causes scanf to read, but not
      to store, a matching non-white-space character.  If the next character in
      stdin does not match, scanf ends.

   o  Format specifications, introduced by the percent sign (%).  A format
      specification causes scanf to read and convert characters in the input
      into values of a specified type.  The value is assigned to an argument in
      the argument list.

 The scanf function reads format-string from left to right. Characters outside
 of format specifications are expected to match the sequence of characters in
 stdin;  the matched characters in stdin are scanned but not stored.  If a
 character in stdin conflicts with format-string, scanf ends.  The conflicting
 character is left in stdin as if it had no been read.

 When the first format specification is found, the value of the first input
 field is converted according to the format specification and stored in the
 location specified by the first entry in argument-list. The second format
 specification converts the second input field and stores it in the second
 entry in argument-list, and so on through the end of format-string.

 An input field is defined as all characters up to the first white-space
 character (space, tab, or new line), up to the first character that cannot be
 converted according to the format specification, or until the field width is
 reached, whichever comes first.  If there are too many arguments for the
 format specifications, the extra arguments are ignored.  The results are
 undefined if there are not enough arguments for the format specifications.

 A format specification has the following form:



   ΓöÇΓöÇ%ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇtypeΓöÇΓöÇ
          Γöé     Γöé  Γöé         Γöé  Γöé     Γöé
          ΓööΓöÇΓöÇ*ΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇwidthΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇhΓöÇΓöÇΓöñ
                                Γöé     Γöé
                                Γö£ΓöÇΓöÇlΓöÇΓöÇΓöñ
                                Γöé     Γöé
                                ΓööΓöÇΓöÇLΓöÇΓöÇΓöÿ

 Each field of the format specification is a single character or a number
 signifying a particular format option.  The type character, which appears
 after the last optional format field, determines whether the input field is
 interpreted as a character, a string, or a number.  The simplest format
 specification contains only the percent sign and a type character (for
 example, %s).

 Each field of the format specification is discussed in SCANF Format Tags. If a
 percent sign (%) is followed by a character that has no meaning as a format
 control character, that character and following characters up to the next
 percent sign are treated as an ordinary sequence of characters;  that is, a
 sequence of characters that must match the input.  For example, to specify a
 percent-sign character, use %%.

 The scanf function scans each input field character by character. It might
 stop reading a particular input field either before it reaches a space
 character, when the specified width is reached, or when the next character
 cannot be converted as specified.  When a conflict occurs between the
 specification and the input character, the next input field begins at the
 first unread character.  The conflicting character, if there was one, is
 considered unread and is the first character of the next input field or the
 first character in subsequent read operations on stdin.

 The scanf function returns the number of fields that were successfully
 converted and assigned.  The return value does not include fields that were
 read but not assigned.

 The return value is EOF for an attempt to read at end-of-file if no conversion
 was performed. A return value of 0 means that no fields were assigned.
 Related Information

   o  fscanf  - Read Formatted Data
   o  printf  - Formatted Print
   o  sscanf  - Read Data
   o  wchar.h

 Example

  #include <wchar.h>

  int main(void) {
      int i;
      float fp;
      char c, s[81];
      wchar_t wc;
      wchar_t ws[81];

      printf("Enter an integer, a real number, a character, a string,\n"
         "a multi-byte character, and a multi-byte string : \n");

      if (scanf("%d %f %c %s %C %S", &i, &fp, &c, s, &wc, ws) != 6)
        printf("Not all of the fields were assigned\n");
      else {
        printf("integer = %d\n", i);
        printf("real number = %f\n", fp);
        printf("character = %c\n", c);
        printf("string = %s\n",s);
        printf("wide-character = %C\n", wc);
        printf("wide-character string = %S\n",ws);
        }
      }


  /*****************  If input is: 12 2.5 a yes,  *******************
  **************  then output should be similar to:  ****************

  Enter an integer, a real number, a character and a string :
  integer = 12
  real number = 2.500000
  character = a
  string = yes

  *******************************************************************/

 This example scans various types of data:
 SCANF Format Tags

 The scanf format specification fields are described below.

  *
 An asterisk (*) following the percent sign suppresses assignment of the next
 input field, which is interpreted as a field of the specified type.  The field
 is scanned but not stored.

  width

 The width is a positive decimal integer controlling the maximum number of
 characters to be read from stdin. No more than width characters are converted
 and stored at the corresponding argument.  Fewer than width characters are
 read if a white-space character (space, tab, or new line), or a character that
 cannot be converted according to the given format occurs before width is
 reached.

  h, l, L

 The optional prefix l(ell) shows that you use the long version of the
 following type, while the prefix h indicates that the short version is to be
 used.  The corresponding argument should point to a long or double object (for
 the l character), a long double object (for the L character), or a short
 object (with the h character).  The l and h modifiers can be used with the d,
 i, o, x, and u type characters. The l modifier can also be used with the e, f,
 and g type characters.  The L modifier can be used with the e, f and g type
 characters. The l and h modifiers are ignored if specified for any other type.
 Note that the l modifier is also used with the c and s characters to indicate
 a multibyte character or string.

  type

 The type characters and their meanings are in the following table:

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé CHAR-  Γöé TYPE OF INPUT EXPECTED    Γöé TYPE OF ARGUMENT          Γöé
  Γöé ACTER  Γöé                           Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "d"    Γöé Decimal integer           Γöé Pointer to "int"          Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "o"    Γöé Octal integer             Γöé Pointer to "unsigned int" Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "x",   Γöé Hexadecimal integer       Γöé Pointer to "unsigned int" Γöé
  Γöé "X"    Γöé                           Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "i"    Γöé Decimal, hexadecimal, or  Γöé Pointer to "int"          Γöé
  Γöé        Γöé octal integer             Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "u"    Γöé Unsigned decimal integer  Γöé Pointer to "unsigned int" Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "e, f, Γöé Floating-point value con- Γöé Pointer to "float"        Γöé
  Γöé g"     Γöé sisting of an optional    Γöé                           Γöé
  Γöé        Γöé sign (+ or -);  a series  Γöé                           Γöé
  Γöé "E, G" Γöé of one or more decimal    Γöé                           Γöé
  Γöé        Γöé digits possibly con-      Γöé                           Γöé
  Γöé        Γöé taining a decimal point;  Γöé                           Γöé
  Γöé        Γöé and an optional exponent  Γöé                           Γöé
  Γöé        Γöé (e or E) followed by a    Γöé                           Γöé
  Γöé        Γöé possibly signed integer   Γöé                           Γöé
  Γöé        Γöé value                     Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "c"    Γöé Character;  white-space   Γöé Pointer to "char" large   Γöé
  Γöé        Γöé characters that are ordi- Γöé enough for input field    Γöé
  Γöé        Γöé narily skipped are read   Γöé                           Γöé
  Γöé        Γöé when "c" is specified     Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "s"    Γöé String                    Γöé Pointer to character      Γöé
  Γöé        Γöé                           Γöé array large enough for    Γöé
  Γöé        Γöé                           Γöé input field plus a termi- Γöé
  Γöé        Γöé                           Γöé nating null character     Γöé
  Γöé        Γöé                           Γöé ("\0"), which is automat- Γöé
  Γöé        Γöé                           Γöé ically appended           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "n"    Γöé No input read from stream Γöé Pointer to "int", into    Γöé
  Γöé        Γöé or buffer                 Γöé which is stored the       Γöé
  Γöé        Γöé                           Γöé number of characters suc- Γöé
  Γöé        Γöé                           Γöé cessfully read from the   Γöé
  Γöé        Γöé                           Γöé stream or buffer up to    Γöé
  Γöé        Γöé                           Γöé that point in the call to Γöé
  Γöé        Γöé                           Γöé "scanf"                   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "p"    Γöé Pointer to "void" con-    Γöé Pointer to "void"         Γöé
  Γöé        Γöé verted to series of char- Γöé                           Γöé
  Γöé        Γöé acters                    Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "lc"   Γöé Multibyte character con-  Γöé Pointer to "wchar_t"      Γöé
  Γöé        Γöé stant                     Γöé                           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé "ls"   Γöé Multibyte string constant Γöé Pointer to "wchar_t"      Γöé
  Γöé        Γöé                           Γöé string                    Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 To read strings not delimited by space characters, substitute a set of
 characters in brackets ([ ]) for the s (string) type character.  The
 corresponding input field is read up to the first character that does not
 appear in the bracketed character set.  If the first character in the set is a
 caret (^), the effect is reversed:  the input field is read up to the first
 character that does appear in the rest of the character set.

 To store a string without storing an ending NULL character (\0), use the
 specification %ac, where a is a decimal integer.  In this instance, the c type
 character means that the argument is a pointer to a character array.  The next
 a characters are read from the input stream into the specified location, and
 no NULL character is added.

 The input for a %x format specifier is interpreted as a hexadecimal number.


ΓòÉΓòÉΓòÉ 8.5. SPRINTF -- Formatted print to buffer ΓòÉΓòÉΓòÉ


Syntax

#include <stdio.h>
#include <wchar.h>

int sprintf(char *buffer, const char *format-string, ...);

Description

The sprintf function formats and stores a series of characters and values in
the array buffer. Any argument-list is converted and put out according to the
corresponding format specification in the format-string.

The format-string consists of ordinary characters and has the same form and
function as the format-string argument for the printf function.  See printf for
a description of the format-string and arguments.

The sprintf function returns the number of characters written in the array, not
counting the ending null character.
Related Information

   o  fprintf  - Write Formatted Data
   o  printf  - Formatted Print
   o  sscanf  - Read Data
   o  wchar.h

 Example

  #include <wchar.h>

  char buffer[200];
  int i, j;
  double fp;
  char *s = "baltimore";
  char c;

  int main(void) {
      c = 'l';
      i = 35;
      fp = 1.7320508;

      /* Format and print various data */

      j = sprintf(buffer, "%s\n", s);
      j += sprintf(buffer+j, "%c\n", c);
      j += sprintf(buffer+j, "%d\n", i);
      j += sprintf(buffer+j, "%f\n", fp);

      printf("\nstring:\n%s\ncharacter count = %d\n", buffer, j);

      }


  /*********************  Output should be similar to:  *************

  string:
  baltimore
  l
  35
  1.732051

  character count = 24

  *******************************************************************/

 This example formats several data values to a buffer and prints out the
 results using printf.


ΓòÉΓòÉΓòÉ 8.6. SSCANF -- Read data ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int sscanf(const char *buffer, const char *format, ...);

Description

The sscanf function reads data from buffer into the locations given by the
argument list.  Each argument must be a pointer to a variable with a type that
corresponds to a type specifier in the format string. See scanf for a
description of the format string.

The sscanf function returns the number of fields that were successfully
converted and assigned.  The return value does not include fields that were
read but not assigned.

The return value is WEOF when the end of the string is encountered before
anything is converted.
Related Information

   o  fscanf  - Read Formatted Data
   o  scanf  - Read Data
   o  sprintf  - Formatted Print to Buffer
   o  wchar.h

 Example

  #include <stdio.h>

  int main(void) {
      char    *tokenstring = "15 12 14";
      wchar_t *widestring = (wchar_t)"ABC Z";
      wchar_t  ws[81];
      wchar_t  wc;
      int   i;
      float fp;
      char  s[81];
      char  c;

      /* Input various data                              */
      sscanf(tokenstring, "%s %c%d%f", s, &c, &i, &fp);
      sscanf(widestring, "%S%C", ws,&wc);
      /* If there were no space between %s and %c,       */
      /* sscanf would read the first character following */
      /* the string, which is a blank space.             */

      /* Display the data */
      printf("\nstring = %s\n",s);
      printf("character = %c\n",c);
      printf("integer = %d\n",i);
      printf("floating-point number = %f\n",fp);
      printf("wide character string = %S\n",ws);
      printf("wide character = %C\n",wc);
      }


  /*****************  Output should be similar to:  *****************

  string = 15
  character = 1
  integer = 2
  floating-point number = 14.000000
  wide character string = ABC
  wide character = Z

  *******************************************************************/

 This example uses sscanf to read various data from the string tokenstring, and
 then displays the data.


ΓòÉΓòÉΓòÉ 9. String Collation Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 9.1. STRCOLL -- Compares strings ΓòÉΓòÉΓòÉ


Syntax

#include <string.h>
#include <wchar.h>

int strcoll(const char *string1, const char *string2);

Description

The strcoll function compares two strings using the collating sequence
specified by the program's locale.

The strcoll function returns a value indicating the relationship between the
strings, as listed below.

Value               Meaning
________________________________________________________
Less than 0         string1 less than string2
0                   string1 equivalent to string2
Greater than 0      string1 greater than string2

Related Information

   o  setlocale  - Set Locale
   o  wcscmp  - Compare wchar_t Strings
   o  wcsncmp  - Compare wchar_t Strings
   o  string.h

 Example

  #include <stdio.h>
  #include <string.h>
  #include <wchar.h>
  #include <locale.h>

  int main(int argc, char ** argv) {
      int  result;

      if ( argc != 3 )
         printf( "Usage: %s string1 string2\n", argv[0] );

      else {
        printf("setlocale set as - %s\n\n",setlocale(LC_ALL,""));
        result = strcoll( argv[1], argv[2] );

        if ( result == 0 )
          printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] );
        else if ( result < 0 )
          printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] );
        else
          printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] );
        }
      }


  /******************  If the input is the strings  ***********************
  ****************  "firststring" and "secondstring",  ********************
  *******************  then the expected output is:  **********************

  "firststring" is less than "secondstring"

  *************************************************************************/

 This example compares the two strings passed to main.


ΓòÉΓòÉΓòÉ 9.2. STRXFRM -- Transforms strings with reference to Locale ΓòÉΓòÉΓòÉ


Syntax

#include <string.h>
#include <wchar.h>

size_t strxfrm(char *string1, const char *string2, size_t count);

Description

The strxfrm function transforms the string pointed to by string2 and places the
result into the string pointed to by string1.  The transformation is determined
by the program's current locale.  The transformed string is not necessarily
readable, but can be used with the strcmp or strncmp functions.

The strxfrm function returns the length of the transformed string, excluding
the terminating null character.  If the value returned is equal to or greater
than count, the contents of the transformed string are indeterminate.
Related Information

   o  localeconv  - Query Locale Conventions
   o  setlocale  - Set Locale
   o  strcmp  - Compare Strings
   o  strcmpi - Compare Strings
   o  strcoll  - Compare Strings
   o  stricmp - Compare Strings
   o  strncmp  - Compare Strings
   o  strnicmp - Compare Strings
   o  string.h

 Example

  #include <stdio.h>
  #include <string.h>

  int main(void) {
      char *string1, buffer[80];
      int length;
      char *s1[8];
      char *s2[8];

      printf("Type in a string of characters.\n ");

      string1 = gets(buffer);

      length = strxfrm(NULL, string1, 0);

      printf("You would need a %d element array to hold the string\n",length);
      printf("\n\n%s\n\n transformed according",string1);
      printf(" to this program's locale. \n");

      length = strxfrm(s1,"choice",6);
      length = strxfrm(s2,"crumby",6);

      if (strcmp(s1,s2) < 0)
        printf("\nchoice\ncrumby\n");
      else
        printf("\ncrumby\nchoice\n");
      }

 This example prompts the user to input a string of characters, then uses
 strxfrm to transform the string and return its length.  It also shows
 collation weights for locale after transformation.


ΓòÉΓòÉΓòÉ 9.3. WCSCOLL -- Compares wide-character strings ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int wcscoll(const wchar_t *WcString1, const wchar_t *WcString2);

Description

The wcscoll subroutine compares the two wide-character strings pointed to by
the WcString1 and WcString2 parameters based on the collation values specified
by the LC_COLLATE environment variable of the current locale.  Note: The
wcscoll subroutine differs from the wcscmp subroutine in that the wcscoll
subroutine compares wide-characters based on their collation values, while the
wcscmp subroutine compares wide characters based on their ordinal values.  The
wcscoll subroutine is less efficient in terms of time than the wcscmp
subroutine because of  the overhead of obtaining the collation values from the
current locale.  The wcscoll subroutine may be unsuccessful if the
wide-character strings specified by the WcString1 or WcString2 parameter
contains characters outside the domain of the current collating  sequence.
Parameters  WcString1   Contains a pointer to a wide-character string.
WcString2   Contains a pointer to a wide-character string.  Return Values  The
wcscoll subroutine returns the following values:  < 0  The collation value of
the WcString1 parameter is less than that of the WcString2 parameter.  =0   The
collation value of the WcString1 parameter is equal to that of the WcString2
parameter.  >0   The collation value of the WcString1 parameter is greater than
that of the WcString2 parameter.  The wcscoll subroutine indicates error
conditions by setting the errno global variable.  However, there is no return
value to indicate an error.  To check for errors, errno should be set to 0,
then checked upon return from the wcscoll subroutine.  If errno is nonzero, an
error occurred.
Related Information

   o  wcscmp
   o  wchar.h

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      wchar_t temp1[255], temp2[255];
      char *s = "crumby";
      char *t = "choice";

      printf("\nCalling setlocale\n");
      printf("Setlocale returns: %s \n", setlocale(LC_ALL, ""));

      mbstowcs(temp1, s, strlen(s)+1);
      mbstowcs(temp2, t, strlen(t)+1);

      if(wcscoll(temp1, temp2) > 0)
        printf("%S is greater than %S\n",temp1,temp2);
      else
        printf("%S is less than %S\n",temp1,temp2);

      } /* end main */

 This example sets the current locale and compares two wide-character strings
 with respect to the current locale.


ΓòÉΓòÉΓòÉ 9.4. WCSXFRM -- Wide char strings to wide char codes of current Locale ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

size_t wcsxfrm(wchar_t *WcString1, const wchar_t *WcString2, size_t Number);

Description

The wcsxfrm subroutine transforms the wide-character string specified by the
WcString2 parameter into a string of wide character codes, based on the
collation values of the wide-characters in the current locale as specified by
the LC_COLLATE category. No  more  than  the  number  of character codes
specified by  the Number parameter are copied into the array specified by the
WcString1 parameter.  This transformation is such that when two such
transformed wide-character strings  are  obtained  and  the transformed strings
are compared using the wcscmp subroutine, the result obtained would  be  the
same as that obtained by a direct call to the wcscoll subroutine on the two
original wide-character strings.
Parameters

 WcString1 Contains a pointer to the destination wide-character string.

 WcString2 Contains a pointer to the source wide-character string.

 Number    Specifies the maximum number of wide-character codes to place into
           the array specified by WcString1.

 Return Values  If the WcString1 parameter is a NULL pointer, the wcsxfrm
 subroutine returns the number of wide-character elements (not including the
 wide-character null terminator) required to store the transformed
 wide-character string.  If the count specified by the Number parameter is
 sufficient to hold the transformed string in the WcString1 parameter,
 including the wide-character null terminator, the return value is set to the
 actual number of wide-character elements placed in the WcString1 parameter,
 not including the wide-character null.  If the return value is equal to or
 greater than the value specified by the Number parameter, the contents of the
 array pointed to by the WcString1 parameter are indeterminate.  This occurs
 whenever the Number parameter value is too small to hold the entire
 transformed string.  If the wide-character string pointed to by the WcString2
 parameter contains wide-character codes outside  the domain of the collating
 sequence defined by the current locale, EINVAL is returned.
 Related Information

   o  wcscmp
   o  wcscoll

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      char *string1 = "Armadillo aerosol chunks";
      size_t  length, l1, l2;
      wchar_t wstring[100];
      wchar_t ws1[50];
      wchar_t ws2[50];
      wchar_t wsa[50];
      wchar_t wsb[50];

      mbstowcs(wstring,string1,100);

      printf("\nLocale now set to --> %s",setlocale(LC_ALL,"Es_ES") );
      length = wcsxfrm(NULL, wstring, 100);
      printf("\n%d wide character element array needed to hold the transformed string",length);
      printf("\n%S\n",wstring);

      mbstowcs(wsa,"llama",50);
      mbstowcs(wsb,"lusty",50);

      l1 = wcsxfrm(ws1,wsa,6);
      l2 = wcsxfrm(ws2,wsb,6);

      if (wcscmp(ws1,ws2) < 0)
        printf("\nlength1-%i-%6S -less than- length2-%i-%6S\n",l1,wsa,l2,wsb);
      else
        printf("\nlength2-%i-%6S -less than- length1-%i-%6S\n",l2,wsb,l1,wsa);

      }

 This example transforms the wide-character string specified by the "temp2"
 parameter into a string of wide-character codes, based on the collation values
 of the wide-characters in the current locale as specified by the LC_COLLATE
 category.


ΓòÉΓòÉΓòÉ 10. Date/Time and Monetary Formatting Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 10.1. STRFMON -- Formats monetary strings ΓòÉΓòÉΓòÉ


Syntax

#include <monetary.h>

ssize_t strfmon(char *s, size_t maxsize, const char *format, ...);

Description

The strfmon subroutine converts numeric values to monetary strings according to
the specifications in the Format parameter. This parameter also contains
numeric values to be converted. Characters are placed into the S array, as
controlled by the Format parameter.  The LC_MONETARY category governs the
format of the conversion.  The strfmon subroutine can be called multiple times
by including additional format structures, as specified by the Format
parameter.  The Format parameter specifies a character string that can contain
plain characters and conversion specifications.  Plain characters are copied to
the output stream.  Conversion specifications result in the fetching of zero or
more arguments, which are converted and formatted.  If there are insufficient
arguments for the Format parameter, the results are undefined.  If arguments
remain after the Format parameter is exhausted, the excess arguments are
ignored.  A conversion specification consists of a % (percent) sign, optional
flags, optional field width, optional left precision, optional right precision,
and a required conversion character that determines the conversion to be
performed.
Flags One or more of the following optional flags can be specified to control
the conversion:

 =f        An = (equal sign) followed by a single character that specifies the
           numeric fill character.  The default numeric fill character is the
           space character.  This flag does not affect field width filling,
           which always uses the space character.  This flag is ignored unless
           a left precision is specified.

 \^        Does not use grouping characters when formatting the currency
           amount.  The default is to insert grouping characters if defined for
           the current locale.

 + or (    Determines the representation of positive and negative currency
           amounts.  Only one of these flags may be specified.  The locale's
           equivalent of + and - are used if + is specified.  The locale's
           equivalent of enclosing negative amounts within parentheses is used
           if ( is specified.  If neither flag is included, a default specified
           by the current locale is used.

 !         Suppresses the currency symbol from the output conversion.

 Field Width

 w         The decimal-digit string, w, specifies the minimum field width in
           which the result of the conversion is right-justified.  If -w is
           specified, the result is left-justified.

 Left Precision

 #n        A # (pound sign) followed by a decimal-digit string, n, specifies
           the maximum number of digits to be formatted to the left of the
           radix character.  This option can be specified to keep formatted
           output from multiple calls to the strfmon subroutine aligned in the
           same columns.  It can also be used to fill unused positions with a
           special character (for example, $***123.45).  This option causes an
           amount to be formatted as if it has the number of digits specified
           by the n variable.  If more than n digit positions are required,
           this option is ignored.  Digit positions in excess of those required
           are filled with the numeric fill character set with the =f flag.  If
           defined for the current locale and not suppressed with the \^ flag,
           grouping is applied to the fill characters and regular digits. If
           the fill character is not 0, however, grouping separators following
           a fill character  are replaced by the fill character (for example,
           $0,001,234.56 and $****1,234.56).

 Right Precision

 .p        A .(period) followed by a decimal digit string, p, specifies the
           number of digits after  the radix character.  If the value of the p
           variable is 0, no radix character is used.  If a right precision is
           not specified, a default specified by the current locale is use.
           The amount being formatted is rounded to the specified number of
           digits prior to formatting.

 Conversion Characters

 i         The double argument is formatted according to the current locale's
           international  currency format; for example, in the U.S.: 1,234.56.

 n         The double argument is formatted according to the current locale's
           national  currency  format;  for  example,  in  the  U.S.:
           $1,234.56.

 %         No argument is converted; the conversion specification %% is
           replaced by a single %.

 Parameters

 S         Contains the output of the strfmon subroutine.

 MaxSize   Specifies the maximum number of bytes (including the null
           terminating byte) that may be placed in the S parameter.

 Format    Contains characters and conversion specifications.

 Return Values If successful, and if the number of resulting bytes (including
 the terminating null character) is not more than the number of bytes specified
 by the MaxSize parameter, the strfmon subroutine returns the number of bytes
 placed into the array pointed to by the S parameter.  Otherwise, -1 is
 returned and the contents of the S array are indeterminate.
 Related Information

   o  scanf
   o  strftime
   o  strptime
   o  wcsftime
   o  monetary.h

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      char temp1[255], buffer[256];
      double num = 0.0;
      size_t rc;

      printf("Setlocal returns: %s \n", setlocale(LC_ALL, ""));

      num = 123456.789;

      rc = strfmon(temp1,sizeof(temp1),"Monetary %n",num);

      printf("strfmon rc = %ld\n",rc);
      printf("Monetary value is %.2f    %s\n",num,temp1);

      } /* end main */

 This example sets the locale and prints out the monitary information with
 respect to that locales specification.


ΓòÉΓòÉΓòÉ 10.2. STRFTIME -- Formats time and date ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

size_t strftime(char *String, size_t Maxsize, const char *Format,
            const struct tm *TmPtr);

Description

The strftime subroutine converts the internal time and date specification of
the tm structure, which is pointed to by the TmPtr parameter, into a character
string pointed to by the String parameter under the direction of the format
string pointed to by the Format parameter.  The actual values for the format
specifiers are dependent on the current settings for the  LC_TIME Category.
The tm structure values may be assigned by the user or generated by the
localtime or gmtime subroutine.  The resulting string is similar to the result
of the printf Format parameter, and is placed in the memory location addressed
by the String parameter.  The maximum length of the string is deteremined by
the Maxsize parameter and terminates with a null character.  Many conversion
specifications are the same as those used by the date command.  The
interpretation of some conversion specifications is dependent on the current
locale of the process.  The Format parameter is a character string containing
two types of objects: plain characters that are simply placed in the output
string, and conversion specifications  that  convert  information from the
TmPtr parameter into readable form in the output string.   Each conversion
specification is a  sequence  of  this form:  %[[-]width][.precision]type  A %
(percent sign) introduces a conversion specification.  An optional
decimal-digit string specifies a minimum field width.  A converted value that
has fewer characters than the field width is padded with spaces to the left.
If the decimal digit string is preceded by a - (minus sign), padding with
spaces occurs to the right of the converted value.  If no width is given, the
appropriate default width is used for numeric  fields, with the field padded to
the left with zeros, as required.  For strings, the output  field  is  made
exactly wide enough to contain the string.  An optional precision value gives
the maximum number of characters to be printed for the conversion
specification.  The precision value  is  a decimal-digit string preceded by a
period.  If the  value  to be output is longer than the precision, the string
is truncated on the right.  The type of conversion is specified by one or two
conversion characters.  The characters and their meanings are:

 %a        Represents the locale's abbreviated weekday name (for example,Sun).

 %A        Represents the locale's full weekday name (for example, Sunday).

 %b        Represents the locale's abbreviated month name (for example,Jan).

 %B        Represents the locale's full month name (for example, January).

 %c        Represents the locale's date and time format.

 %C        Represents the century.

 %d        Represents the day of the month as a decimal number (01 to 31).

 %D        Represents the date in %m/%d/%y format (for example, 01/31/91).

 %e        Represents the day of the month as a decimal number ( 1 to 31). An
           single digit is preceded by a space character.

 %h        Same as %b.

 %H        Represents the 24-hour-clock hour as a decimal number (00 to 23).

 %I        Represents the 12-hour-clock hour as a decimal number (01 to 12).

 %j        Represents the day of the year as a decimal number (001 to 366).

 %m        Represents the month of the year as a decimal number (01 to 12).

 %M        Represents the minute of the hour as a decimal number (00 to 59).

 %n        Specifies a new-line character.

 %p        Represents the locale's AM or PM string.

 %r        Represents 12-hour clock time with AM/PM notation(%I:%M:%S%p).

 %R        Represents 24-hour-clock time in the format %H:%M.

 %S        Represents the second of the minute as a decimal number (00 to 61).

 %t        Specifies a tab character.

 %T        Represents 24-hour-clock time in the format %H:%M:%S.

 %u        Represents the day of the week as a decimal number (1 to 7). Monday
           is considered as 1.

 %U        Represents the week of the year as a decimal number (00 to 53).
           Sunday is considered the first day of the week.

 % V       Represents the week of the year as a decimal number (01 to 53).
           Monday is considered the first day of the week.  If the week
           containing 1 January has four or more days in the new year, then it
           is considered week 1; otherwise, it is week 53 of the previous year,
           and the next week is week 1.

 %w        Represents the day of the week as a decimal number (0 to 6). Sunday
           is considered as 0.

 %W        Represents the week of the year as a decimal number (00 to 53).
           Monday is considered the first day of the week. All days in a new
           year preceding the first Monday are considered to be week 0.

 %x        Represents the locale's date format.

 %X        Represents the locale's time format.

 %y        Represents the year of the century (00 to 99).

 %Y        Represents the year with century as a decimal number (1989).

 %Z        Represents the time-zone name if one can be determined (for example,
           EST).  No characters are displayed if a time zone cannot be
           determined.

 %%        Specifies a % (percent) sign.
  Parameters

   o  String  Pointer to the string to hold the formatted time.

   o  Maxsize Maximum length of string pointed to by the String parameter.

   o  Format  Pointer to the format character string.

   o  TmPtr  Pointer to the time structure that is to be converted.

 Return Values  If the total number of resulting bytes, including the
 terminating null byte, is not more than the Maxsize value, the strftime
 subroutine returns the number of bytes placed into the array pointed to by the
 String parameter.  Otherwise, 0 is returned and the contents of the array are
 indeterminate.
 Related Information

   o  strfmon
   o  strptime
   o  mbstowcs
   o  wcsftime
   o  localtime
   o  gmtime
   o  printf

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <time.h>
  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      char temp[255];
      time_t ltime;
      size_t rc;
      struct tm *ptmTemp;

      printf("\nCalling setlocale\n");
      printf("Setlocale returns: %s \n", setlocale(LC_ALL, ""));

      time(<ime);

      ptmTemp = localtime(<ime);

      rc = strftime(temp,sizeof(temp),"At   Time %9X   Date %9x %a %A %b %B %h",ptmTemp);

      printf("strftime rc = %ld\n",rc);
      printf("%s\n",temp);
      }

 This code fragment sets the locale and calls STRFTIME to print out the time
 with respect to that locales format.


ΓòÉΓòÉΓòÉ 10.3. STRPTIME -- Converts a character string to a time value ΓòÉΓòÉΓòÉ


Syntax

#include <time.h>

char *strptime(const char *String, const char *Format, struct tm *TmPtr);

Description

The strptime subroutine converts the characters in the String parameter to
values that are stored in the TmPtr structure, using the format specified by
the Format parameter.  Parameters

   o  String   Contains the character string to be converted by the strptime
      subroutine.

   o  Format  Contains format specifiers for the strptime subroutine. The
      Format parameter contains zero or more specifiers.  Each specifier is
      composed of one of the following:

        -  One or more white-space characters

        -  An ordinary character (neither % nor a white-space character)

        -  A format specifier. The  LC_TIME category defines the locale values
         for the format specifiers.  The following format specifiers are
         supported:

           %a        Represents the weekday name; abbreviated or full (for
                     example, Sun or Sunday) defined for the locale.

           %A        Same as %a.

           %b        Represents the month name ; abbreviated or full (for
                     example, Jan or January) defined for the locale.

           %B        Same as %b.

           %c        Represents the date and time format defined by the
                     locale(%x %X).

           %C        Represents the century number (0,99).

           %d        Represents the day of the month as a decimal number (1 to
                     31).

           %D        Represents the date in %m/%d/%y format (for example,
                     12/31/93).

           %e        Same as %d.

           %h        Same as %b.

           %H        Represents the 24-hour-clock hour as a decimal number (00
                     to 23).

           %I        Represents the 12-hour-clock hour as a decimal number (01
                     to 12).

           %j        Represents the day of the year as a decimal number (001 to
                     366).

           %m        Represents the month as a decimal number (01 to 12).

           %M        Represents the minutes of the hour as a decimal number (00
                     to 59).

           %n        Specifies any white space.

           %p        Represents the AM or PM string defined by the am_pm
                     statement.

           %r        Represents the time in the format %I:%M:%S%p.

           %R        Represents the time in the format %H:%M (for example,
                     16:5).

           %S        Represents the seconds (00 to 61).

           %t        Specifies any white space.

           %T        Represents 24-hour-clock time in the format %H:%M:%S.

           %U        Represents the week of the year as a decimal number (00 to
                     53). Sunday is considered the first day of the week.

           %w        Represents the day of the week as a decimal number (0 to
                     6). Sunday is considered as 0.

           %W        Represents the week of the year as a decimal number (00 to
                     53). Monday is considered the first day of the week.

           %x        Represents the date, defined by the locale's date format.

           %X        Represents the time, defined by the locale's time format.

           %y        Represents the year of the century (00 to 99).

           %Y        Represents the year including the century (for example,
                     1939).

           %%        Specifies a % (percent sign) character. A format
         specification consisting of white-space characters is performed  by
         reading input until the first non-white-space character (which  is
         not  read)  or up to no more characters can be read.  A format
         specification consisting of an ordinary character is performed by
         reading the next character from the String parameter. If  this
         character  differs  from  the character comprising  the directive,
         the  directive  fails and the differing character and any characters
         following  it remain unread.  Case is ignored when matching String
         items, such as month or weekday names.

   o  TmPtr   Specifies the structure to contain the output of the strptime
      subroutine.  If a conversion fails, the contents of the TmPtr structure
      are undefined.

 Return Values  If successful, the strptime subroutine returns a pointer to the
 character following the last character parsed.  Otherwise, a null pointer is
 returned.
 Related Information

   o  scanf
   o  strfmon
   o  strftime
   o  wcsftime

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <time.h>

  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      char temp[255];
      const char *buf;
      time_t ltime;
      char rc;
      char *rcp;
      struct tm *ptmTemp;

      ptmTemp = malloc(sizeof(*ptmTemp));

      strcpy(temp,"12:34:56 10/21/93");

      printf("\nCalling setlocale\n");
      printf("Setlocale returns: %s \n", setlocale(LC_ALL, ""));

      rcp = strptime(temp, "%T %D", ptmTemp);

      if(rcp != NULL) {
        rc = strftime(temp,sizeof(temp),"At   Time %9X   Date %9x %A %B %r",ptmTemp);
        printf("%s\n",temp);
        return(1);
        }

      return (0);
      }

 This example loads the locale and sets the day of the week and the date in the
 time structure to 10/21/93 and prints out the results with respect to the
 locale loaded.


ΓòÉΓòÉΓòÉ 10.4. WCSFTIME -- Converts date and time into a wide character string ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

size_t wcsftime(wchar_t *WcString, size_t Maxsize, const char *Format,
            const struct tm *TmPtr);

Description

The wcsftime subroutine formats the data in the TmPtr parameter according to
the specification contained in the Format parameter and places the resulting
wide character string into the WcString parameter.  Up to Maxsize-1
wide-characters are placed into the WcString parameter, terminated by a
wide-character NULL.  The wcsftime subroutine behaves as if the character
string generated by the strftime subroutine is passed to the mbstowcs
subroutine as the character string parameter and the mbstowcs subroutine places
the result in the WcString parameter of the wcsftime subroutine, up to the
limit of wide character codes specified by the Maxsize parameter  Parameters

   o  WcString Contains the output of the wcsftime subroutine.

   o  Maxsize  Specifies the maximum number of bytes (including the wide
      character  null-terminating  byte) that  may  be  placed  in  the
      WcString parameter.

   o  Format  Contains format specifiers.  The  LC_TIME category defines the
      locale values for the format specifiers.  The Format parameter can use
      the same format specifiers as strftime.

   o  TmPtr  Contains the data to be converted by the wcsftime subroutine.

 Return Values If successful, and if the number of resulting wide-characters
 (including  the  wide-character null-terminating byte) is no more than the
 number of bytes specified by the Maxsize parameter, the wcsftime subroutine
 returns the number of wide-characters (not including the wide-character
 null-terminating byte) placed in the WcString parameter.  Otherwise, 0 (zero)
 is returned and the contents of the WcString parameter are indeterminate.
 Related Information

   o  strfmon
   o  strftime
   o  strptime
   o  mbstowcs

 Example

  #include <stdlib.h>
  #include <stdio.h>
  #include <time.h>
  #include <wchar.h>
  #include <locale.h>

  int main (void) {
      wchar_t temp[255];
      time_t ltime;
      size_t rc;
      struct tm *ptmTemp;

      printf("\nCalling setlocale\n");
      printf("Setlocale returns: %s \n", setlocale(LC_ALL, ""));

      time(<ime);
      ptmTemp = localtime(<ime);

      rc=wcsftime(temp,sizeof(temp),"At   Time %9X   Date %9x %a %A %b %B %h",ptmTemp);

      printf("wcsftime rc = %ld\n",rc);
      printf("%ls\n",temp);
      }

 This example sets the locale and calls WCSFTIME to print out the time in wide
 character with respect to that locales format.


ΓòÉΓòÉΓòÉ 10.5. WCSTOL -- Converts a wide char string to long int representation ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

long int wcstol(const wchar_t *nptr, wchar_t **endptr, int base);

Description

The wcstol subroutine converts the initial portion of the wide character string
pointed to by the nptr parameter to a signed long integer representation.  The
input wide character string is first broken down into three parts:  1.   An
initial, possibly empty, sequence of white-space wide character codes (as
specified by the iswspace subroutine).  2.   A subject sequence interpreted as
an integer and represented in a radix determined by the base parameter.  3.   A
final wide character string of one or more unrecognized wide character codes,
including the terminating wide character null of the input wide character
string.  If possible, the subject is then converted to an integer and the
result is returned.  The base parameter can take the following values: 0
through 9, or a (or A) through z (or Z).  Potentially, there can be 36 values
for the base.   If the base value is 0, the expected form of the subject string
is that of an integer constant, optionally preced ed by a plus or minus sign,
but not including the integer suffix. If the base value is between 2 and 36,
the expected form  of  the subject sequence is a sequence of letters and digits
representing an integer in the radix specified by the base parameter, option
ally preceded by a plus or minus sign, but not  including  an integer suffix.
The letters a (or A) through z (or Z) are ascribed the values of 10 to 35.
Only letters whose values are less than that of the base are permitted.  If
the value of base is 16, the characters  0x  or  0X  may  optionally  precede
the sequence of letters or digits, following the sign, if present.  The wide
character string is parsed to skip the initial space characters (as determined
by the iswspace subroutine).  Any non space character signifies  the start of a
subject string that may form an integer in the radix specified by the base
parameter. The  subject  sequence is defined to be the longest initial
substring that  is a long integer of the expected form.  Any character not
satisfying this form begins the final portion of the wide character string
pointed to by the endptr parameter on return from the call to the wcstol
subroutine.
Parameters  nptr  Contains a pointer to the wide character string to be
converted to a double-precision number.  endptr  Contains a pointer to the
position in the nptr string where a wide character is found that is not a valid
character for the purpose of this conversion.  base  Specifies the radix in
which the characters are interpreted.
Return Values  The wcstol subroutine returns the converted value of long
integer if  the  expected form is found.  If no conversion could be  performed,
a value of 0 is returned.  If the converted value is out side the range of
representable values, LONG_MAX or LONG_MIN is returned (according to the sign
of the value),  and  the value of the errno global variable is set to ERANGE.
If the base value specified by the base parameter is not supported, EINVAL is
returned.  If the subject sequence has the expected form, it is interpreted as
an integer constant in the appropriate base.  A pointer to the final string is
stored in the endptr parameter if that parameter is not a null pointer.  If the
subject sequence is  empty or does not have a valid form, no conversion  is
done.  The value of the nptr parameter is stored in the endptr parameter if
that parameter is not a null pointer.  Since 0, LONG_MIN, and LONG_MAX are
returned in the event of an error and are also valid returns if the wcstol
subroutine is successful, applications should set the errno global variable to
0 before calling the wcstol subroutine, and then check the errno global
variable after return.  Then, if the errno global variable has changed, an
error occurred.
Related Information

   o  iswspace - Checks for a valid wide character space.
   o  wcstod  - Converts a wide character string to a double-precision number.
   o  wsctoul  - Converts wide character strings to unsigned long integer.
   o  wchar.h  - Header file for wide character function prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define SIZE  40

  main()
  {

    wchar_t WCString[SIZE],
            *endptr;

    long int retval;

    /** Set errno to 0 so a failure for wcstol can be **detected */
    errno=0;

    mbstowcs(WCString,"-100000",SIZE);

    /*
     **Let WCString point to a wide character null terminated
     ** string containing a signed long integer value
     **
    */

    retval = wcstol ( WCString, &endptr, 10 );
    /* Check errno, if it is non-zero, wcstol failed */
    if (errno != 0)
    {
      /*Error handling*/
      printf("An error occurred during conversion\n");
    }
    else if (retval == 0)
    {
      /* No conversion could be performed */
      /* Handle this case accordingly. */
      printf("No conversion could be performed\n");
    }
    /* retval contains long integer */
    printf("This should be a long integer %ld\n",retval);
  }

 The following converts a wide character string to a signed long integer.


ΓòÉΓòÉΓòÉ 10.6. WCSTOUL -- Converts wide char strings to unsigned long int ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

unsigned long wcstoul(const wchar_t *nptr,
                  wchar_t **endptr, int base);

Description

The wcstoul subroutine converts the initial portion of the wide character
string pointed to by the nptr parameter to an unsigned long integer
representation.  To  do  this, it parses the wide character string pointed to
by the nptr parameter to obtain a valid string (that is, subject string) for
the purpose of conversion to an unsigned long integer.  It then points the
endptr parameter to the position where an unrecognized character, including the
terminating null, is found.  The base specified by the base parameter can take
the following values:  0  through 9, a (or A) through z (or Z). Potentially,
there can be 36 values for the base.  If the base value is 0, the expected form
of the subject string is that  of  an  unsigned integer constant, with an
optional + (plus) or - (minus)  sign, but not including the integer suffix. If
the base value is between 2 and 36, the expected form of the subject sequence
is  a sequence of letters and digits representing an integer with the  radix
specified by the base parameter, optionally preceded by a + or - sign, but not
including an integer suffix.  The letters a (or A) through z (or Z) are
ascribed the values of 10 to  35.   Only letters whose values are less than
that of the base are permitted.  If the value  of  base is 16, the characters
0x or 0X may optionally precede the sequence of letters or digits, following
the sign, if present.  The wide character string is parsed to skip the initial
white space characters (as determined by the iswspace subroutine).  Any
non-space character signifies the  start of a subject string that may form an
unsigned long integer in the radix specified by the base parameter.  The
subject sequence is defined to be the longest initial substring that is an
unsigned long integer of the expected form.  Any character not satisfying this
expected form begins the final portion of the wide character string pointed to
by the endptr parameter on return from the call to this subroutine.
Parameters  nptr Contains a pointer to the wide character string to be
converted to an unsigned long integer.  endptr Contains a pointer to the
position in the nptr string where a wide character is found that is not a valid
character for the purpose of this conversion.  base Specifies the radix in
which the wide characters are interpreted.
Return Values  The wcstoul subroutine returns the converted value of the
unsigned integer if the expected  form  is found.  If no conversion could be
performed, a value of 0 is  returned.  If the converted value is outside the
range of representable values, ULONG_MAX is returned, and the value of the
errno global variable is set to ERANGE.  If the subject sequence has the
expected form, it is interpreted as an integer constant in the appropriate
base.  A pointer to the final string is stored in the endptr parameter if that
parameter is not a null pointer.  If the subject sequence is empty or does not
have a valid form, no conversion is done and the value of the nptr parameter is
stored in the endptr parameter if it is not a null pointer.  If the radix
specified by the base parameter is not supported, EINVAL is returned.  If the
value to be returned is not representable, ERANGE is returned.
Related Information

   o  iswspace - Checks for a valid wide character space.
   o  wcstod  - Converts a wide character string to a double-precision number.
   o  wsctoul  - Converts wide character strings to unsigned long integer.
   o  wchar.h  - Header file for wide character function prototypes.

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define SIZE  40

  main()
  {

    wchar_t WCString[SIZE],
            *endptr;

    unsigned long int retval;

    /** Set errno to 0 so a failure for wcstol can be **detected */
    errno=0;

    mbstowcs(WCString,"100000",SIZE);

    /*
     **Let WCString point to a wide character null terminated
     ** string containing a signed unsigned long integer value
     **
    */

    retval = wcstol ( WCString, &endptr, 10 );
    /* Check errno, if it is non-zero, wcstol failed */
    if (errno != 0)
    {
      /*Error handling*/
      printf("An error occurred during conversion\n");
    }
    else if (retval == ULONG_MAX)
    {
      /* No conversion could be performed */
      /* Handle this case accordingly. */
      printf("No conversion could be performed\n");
    }
    /* retval contains long integer */
    printf("This should be a unsigned long integer %ld\n",retval);
  }

 This example converts a wide character string to an unsigned long integer.


ΓòÉΓòÉΓòÉ 11. WideChar String Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 11.1. WCSCAT -- Appends string1 to string2 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>
wchar_t *wcscat(wchar_t *string1, const wchar_t *string2);

Description.

The wcscat function appends a copy of the string pointed to by string2 to the
end of the string pointed to by string1.

The wcscat function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string. Boundary checking is not performed.

The wcscat function returns the value of string1.
Related Information

   o  strcat  - Concatenate Strings
   o  strncat  - Concatenate Strings
   o  wcsncat  - Concatenate wchar_t Strings
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t buffer1[40];
      wchar_t string[40];
      wchar_t * ptr;

      mbstowcs(buffer1,"computer",9);
      mbstowcs(string," program",9);

      ptr = wcscat( buffer1, string );

      printf( "buffer1 = %S\n", buffer1 );
      }
  /****************  Output should be similar to:  ******************

  buffer1 = computer program

  *******************************************************************/

 This example creates the wide character string "computer program" using
 wcscat.


ΓòÉΓòÉΓòÉ 11.2. WCSCHR -- Searches string1 for a wide character ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t  *wcschr(const wchar_t *ws, wint_t wc);

Description.

The wcschr function searches ws for the occurrence of wc. wc may be a wint_t
null character (L0); the wchar_t null character at the end of ws is included in
the search.

The wcschr function operates on null-terminated wchar_t strings. The ws
argument to this function should contain a wchar_t null character marking the
end of the string.

The wcschr function returns a pointer to the first occurrence of character in
ws. If the character is not found, a NULL pointer is returned.
Related Information

   o  wcscspn  - Find Offset of First wchar_t Match
   o  wcspbrk  - Locate wchar_t Characters in wchar_t String
   o  wcsrchr  - Locate wchar_t Character in wchar_t String
   o  wcsspn  - Search wchar_t Characters in wchar_t String
   o  wcswcs  - Locate wchar_t Substring in wchar_t String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t buffer1[20];
      wchar_t * ptr;
      wchar_t wc = (wchar_t)'p';

      mbstowcs(buffer1,"computer program",17);

      ptr = wcschr( buffer1, wc );

      printf( "The first occurrence of %C in '%S' is '%S'\n",
                         wc, buffer1, ptr );

      }
  /****************  Output should be similar to:  ******************

  The first occurrence of p in 'computer program' is 'puter program'

  *******************************************************************/

 This example finds the first occurrence of the character p in the wide
 character string "computer program".


ΓòÉΓòÉΓòÉ 11.3. WCSCMP -- Compares string1 to string2 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int wcscmp(const wchar_t *ws1, const wchar_t *ws2);

Description.

The wcscmp function compares two wchar_t strings.

The wcscmp function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string. Boundary checking is not performed when a string is added to
or copied.

The wcscmp function returns a value indicating the relationship between the two
strings, as follows:

Value               Meaning
Less than 0         ws1 less than ws2
0                   ws1 identical to ws2
Greater than 0      ws1 greater than ws2.

Related Information

   o  wcsncmp  - Compare wchar_t Strings
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      int  result;
      wchar_t ws1[20];
      wchar_t ws2[20];

      mbstowcs(ws1,"abcdef",7);
      mbstowcs(ws2,"abcdefg",8);

      result=wcscmp( ws1, ws2 );

      if ( result == 0 )
        printf( "\"%S\" is identical to \"%S\"\n", ws1, ws2);
      else if ( result < 0 )
        printf( "\"%S\" is less than \"%S\"\n", ws1, ws2 );
      else
        printf( "\"%S\" is greater than \"%S\"\n", ws1, ws2);
      }
  /****************  Output should be similar to:  ******************

  "abcdef" is less than "abcdefg"

  *******************************************************************/

 This example compares the wide character string ws1 to ws2 using wcscmp.


ΓòÉΓòÉΓòÉ 11.4. WCSCPY -- Copies string2 into string1 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);

Description.

The wcscpy function copies the contents of ws2 (including the ending wchar_t
null character) into ws1.

The wcscpy function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string. Boundary checking is not performed.

The wcscpy function returns the value of ws1.
Related Information

   o  wcsncpy  - Copy wchar_t Strings
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t source[ 80 ];
      wchar_t target[ 80 ];
      wchar_t *wsptr;

      mbstowcs(ws1,"This is the source string",40);
      mbstowcs(ws1,"And this is the target string",40);

      printf( "Target is originally = \"%S\"\n", target );

      wsptr = wcscpy( target, source );

      printf( "After wcscpy, target becomes \"%S\"\n", wsptr );
      }
  /****************  Output should be similar to:  ******************

  Target is originally = "And this is the target string"
  After wcscpy, target becomes "This is the source string"

  *******************************************************************/

 This example copies the contents of source string to a destination string.


ΓòÉΓòÉΓòÉ 11.5. WCSCSPN -- Finds length of complementary wide char substring ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h> /* SAA extension to ANSI */

size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);

Description.

The wcscspn function determines the number of wchar_t characters in the initial
segment of the string pointed to by ws1 that do not appear in the string
pointed to by ws2.

The wcscspn function operates on null-terminated wchar_t strings. The string
arguments to these functions should contain a wchar_t null character marking
the end of the string.

The wcscspn function returns the number of wchar_t characters in the segment.
Related Information

   o  wcsspn  - Search wchar_t Characters in String
   o  wcswcs  - Locate wchar_t Substring in wchar_t String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t ws[ 80 ];
      wchar_t * substring[ 10 ];

      mbstowcs(ws,"This is the source string",40);
      mbstowcs(substring,"axle",10);

      printf( "The first %i characters in the string \"%S\" are not "
         "in the string \"%S\" \n", wcscspn( ws, substring),
         ws, substring );

      }


  /****************  Output should be similar to:  ************************

  The first 10 characters in the string "This is the source string" are not
  in the string "axle"

  *************************************************************************/

 This example uses wcscspn to find the first occurrence of any of the
 characters a, x, l, or e in ws.


ΓòÉΓòÉΓòÉ 11.6. WCSLEN -- Finds length of wide character string ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

size_t wcslen(const wchar_t *ws);

Description.

The wcslen function computes the number of wchar_t characters in the string
pointed to by ws.

The wcslen function returns the number of wchar_t characters that precede the
terminating wchar_t null character.
Related Information

   o  mblen  - Multibyte String Length
   o  strlen  - Determine String Length
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t  ws[ 20 ];

      mbstowcs(ws,"abcdef",7);
      printf( "Length of \"%S\" is %i\n", ws, wcslen( ws ));

      }
  /****************  Output should be similar to:  ******************

  Length of "abcdef" is 6

  *******************************************************************/

 This example computes the length of a wchar_t string.


ΓòÉΓòÉΓòÉ 11.7. WCSNCAT -- Appends wide characters from string2 to string1 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t count);

Description.

The wcsncat function appends up to count wide characters from ws2 to the end of
ws1 and appends a wchar_t null character to the result.

The wcsncat function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcsncat function returns ws1.
Related Information

   o  strncat  - Concatenate Strings
   o  strcat  - Concatenate Strings
   o  wcscat  - Append wchar_t Strings
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t * buffer1;
      wchar_t * buffer2;
      wchar_t * ptr;

      buffer1 = (wchar_t *)malloc(80);
      buffer2 = (wchar_t *)malloc(20);

      mbstowcs(buffer1,"computer",9);
      mbstowcs(buffer2," program",9);

      /* Call wcscat with buffer1 and " program" */

      ptr = wcscat( buffer1, buffer2 );
      printf( "wcscat : buffer1 = \"%S\"\n", buffer1 );

      /* Reset buffer1 to contain just the string "computer" again */

      memset( buffer1, '\0', sizeof( buffer1 ));
      mbstowcs(buffer1,"computer",9);

      /* Call wcsncat with buffer1 and " program" */
      ptr = wcsncat( buffer1, buffer2, 3 );

      printf( "wcsncat: buffer1 = \"%S\"\n", buffer1 );
      }
  /****************  Output should be similar to:  ******************

  wcscat : buffer1 = "computer program"
  wcsncat: buffer1 = "computer pr"

  *******************************************************************/

 This example demonstrates the difference between wcscat and wcsncat. Wcscat
 appends the entire second string to the first whereas wcsncat appends only the
 specified number of characters in the second string to the first.


ΓòÉΓòÉΓòÉ 11.8. WCSNCMP -- Compares subset string2 to string1 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t count);

Description.

The wcsncmp function compares up to count wide characters in ws1 to ws2.

The wcsncmp function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcsncmp function returns a value indicating the relationship between the
two strings, as follows:

Value               Meaning
Less than 0         ws1 less than ws2
0                   ws1 identical to ws2
Greater than 0      ws1 greater than ws2.

Related Information

   o  wcscmp  - Compare wchar_t Strings
   o  strcoll  - Compare wchar_t Strings
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      int  result;
      wchar_t buffer1[20];
      wchar_t buffer2[20];

      mbstowcs(buffer1,"abcdefg",8);
      mbstowcs(buffer2,"abcfg",6);

      result = wcscmp( buffer1, buffer2 );

      printf( "Comparison of each character\n" );
      printf( "  wcscmp: " );

      if ( result == 0 )
        printf( "\"%S\" is identical to \"%S\"\n", buffer1, buffer2);
      else if ( result < 0 )
        printf( "\"%S\" is less than \"%S\"\n", buffer1, buffer2 );
      else
        printf( "\"%S\" is greater than \"%S\"\n", buffer1, buffer2 );

      result = wcsncmp( buffer1, buffer2, 3);

      printf( "\nComparison of only the first 3 characters\n" );
      printf( "  wcsncmp: " );

      if ( result == 0 )
        printf( "\"%S\" is identical to \"%S\"\n", buffer1, buffer2);
      else if ( result < 0 )
        printf( "\"%S\" is less than \"%S\"\n", buffer1, buffer2 );
      else
        printf( "\"%S\" is greater than \"%S\"\n", buffer1, buffer2 );

      }
  /****************  Output should be similar to:  ******************

  Comparison of each character
  wcscmp: "abcdefg" is less than "abcfg"

  Comparison of only the first 3 characters
  wcsncmp: "abcdefg" is identical to "abcfg"

  *******************************************************************/

 This example demonstrates the difference between wcscmp and wcsncmp.


ΓòÉΓòÉΓòÉ 11.9. WCSNCPY -- Copies n wide characters from string2 to string1 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t count);

Description.

The wcsncpy function copies up to count wide characters from ws2 to ws1. If ws2
is shorter than count characters, string1 is padded out to count characters
with wchar_t null characters.

The wcsncpy function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcsncpy function returns ws1.
Related Information

   o  wcscpy  - Copy wchar_t Strings
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t source[ 20 ];
      wchar_t source1[ 20 ];
      wchar_t target[ 20 ];
      wchar_t target1[ 20 ];
      wchar_t * return_string;
      int    index = 5;

      mbstowcs(source,"123456789",10);
      mbstowcs(source1,"123456789",10);
      mbstowcs(target,"abcdefg",8);
      mbstowcs(target1,"abcdefg",8);

      printf( "target is originally = '%S'\n", target );

      return_string = wcscpy( target, source );

      printf( "After wcscpy, target becomes '%S'\n\n", target );

      printf( "target is originally = '%S'\n", target1 );

      return_string = wcsncpy( target1, source1, index );

      printf( "After wcsncpy 'n=5', target becomes '%S'\n", target1 );

      }
  /****************  Output should be similar to:  ******************

  target is originally = 'abcdefg'
  After wcscpy 'n=5', target becomes '123456789'

  target1 is originally = 'abcdefg'
  After wcsncpy, target1 becomes '12345fg'

  *******************************************************************/

 This example demonstrates the difference between wcscpy and wcsncpy.


ΓòÉΓòÉΓòÉ 11.10. WCSPBRK -- Locates occurrence of wide characters from string2 in string1 ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);


Description.

The wcspbrk function locates the first occurrence in the string pointed to by
ws1 of any character from the string pointed to by ws2.

The wcspbrk function returns a pointer to the character, or NULL if no wchar_t
from ws2 occurs in ws1.
Related Information

   o  wcschr  - Search wchar_t String for Given wchar_t
   o  wcscspn  - Find Offset of First wchar_t Match
   o  wcsncmp  - Compare wchar_t Strings
   o  wcsrchr  - Locate wchar_t Character in String
   o  wcsspn  - Search wchar_t Characters in String
   o  wcswcs  - Locate wchar_t Substring in wchar_t String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t  *result;
      wchar_t  ws[ 30 ];
      wchar_t  wc[ 8 ];

      mbstowcs(ws,"Blue Danube",12);
      mbstowcs(wc,"ab",3);

      result = wcspbrk( ws, wc);

      printf("The first occurrence of any of the characters \"%S\" in "
         "\"%S\" is \"%S\"\n", wc, ws, result);

      }
  /*******************  Output should be similar to:  *********************

  The first occurrence of any of the characters "ab" in "Blue Danube" is "anube"

  *************************************************************************/

 This example returns a pointer to the first occurrence in the array string of
 either a or b.


ΓòÉΓòÉΓòÉ 11.11. WCSRCHR -- Locates last occurence of wide character in a string ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcsrchr(const wchar_t *ws, wint_t wi);

Description.

The wcsrchr function locates the last occurrence of wi in the string pointed to
by ws.  The terminating wchar_t null character is considered to be part of the
string.

The wcsrchr function returns a pointer to the character, or a NULL pointer if
wi does not occur in the string.
Related Information

   o  wcschr  - Search wchar_t String for Given wchar_t
   o  wcscspn  - Find Offset of First wchar_t Match
   o  wcsspn  - Search wchar_t Characters in String
   o  wcswcs  - Locate wchar_t Substring in wchar_t String
   o  wcspbrk  - Locate wchar_t Characters in String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t ws[40];
      wchar_t * ptr;
      wint_t    wi = (wint_t)'p';

      mbstowcs(ws,"computer program",19);

      ptr = wcschr( ws, wi );

      printf( "The first occurrence of %C in '%S' is '%S'\n", wi, ws, ptr );

      ptr = wcsrchr( ws, wi );

      printf( "The last occurrence of %C in '%S' is '%S'\n",  wi, ws, ptr );
      }
  /****************  Output should be similar to:  ******************

  The first occurrence of p in 'computer program' is 'puter program'
  The last occurrence of p in 'computer program' is 'program'

  *******************************************************************/

 This example compares the use of wcschr and wcsrchr. It searches the string
 for the first and last occurrence of p in the wide character string.


ΓòÉΓòÉΓòÉ 11.12. WCSSPN -- Finds lingth of wide character substring ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);

Description.

The wcsspn function computes the number of wchar_t characters in the initial
segment of the string pointed to by ws1, which consists entirely of wchar_t
characters from the string pointed to by ws2.

The wcsspn function returns the number of wchar_t characters in the segment.
Related Information

   o  wcschr  - Search wchar_t String for Given wchar_t
   o  wcscspn  - Find Offset of First wchar_t Match
   o  wcsrchr  - Locate wchar_t Character in String
   o  wcsspn  - Search wchar_t Characters in String
   o  wcswcs  - Locate wchar_t Substring in wchar_t String
   o  wcspbrk  - Locate wchar_t Characters in String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  int main(void) {
      wchar_t  ws[20];
      wchar_t  source[8];
      int index;

      mbstowcs(ws,"cabbage",8);
      mbstowcs(source,"abc",4);

      index = wcsspn( ws, source );

      printf( "The first %d characters of \"%S\" are found in \"%S\"\n",
             index, ws, source );
      }
  /****************  Output should be similar to:  ******************

  The first 5 characters of "cabbage" are found in "abc"

  *******************************************************************/

 This example finds the first occurrence in the array string of a character
 that is neither an a, b, nor c.  Because the string in this example is
 cabbage, wcsspn returns 5, the index of the segment of cabbage before a
 character that is not an a, b, or c.


ΓòÉΓòÉΓòÉ 11.13. WCSTOK -- Converts wide-character strings to tokens ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcstok(wchar_t *String1, const wchar_t *String2);

Description

The wcstok function reads a wide-character string1 as a series of zero or more
tokens and wide-character string2 as the set of characters serving as
delimiters of the tokens in string1.  The tokens in string1 can be separated by
one or more of the delimiters from string2.  The tokens in string1 can be
located by a series of calls to wcstok.

In the first call to wcstok for a given string1, wcstok searches for the first
token in  string1, skipping over leading delimiters.  A pointer to the first
token is returned.

To read the next token from string1, call wcstok with a NULL string1 argument.
A NULL string1 argument causes wcstok to search for the next token in the
previous token string.  Each delimiter is replaced by a null character.  The
set of delimiters can vary from call to call, so string2 can take any value.

The first time wcstok is called, it returns a pointer to the first token in
string1.  In later calls with the same token string, wcstok returns a pointer
to the next token in the string.  A NULL pointer is returned when there are no
more tokens.  All tokens are null-terminated.
Parameters

 String1   Contains a pointer to the wide-character string to be searched.

 String2   Contains a pointer to the string of wide-character token delimiters.

 Return Values

 The wcstok subroutine returns a pointer to the first wide-character of a
 token. A null pointer is returned if there is no token found.
 Related Information

   o  wcsspn
   o  wcswcs
   o  wcstoul
   o  wcstol
   o  wchar.h

 Example

  #include <stdio.h>
  #include <stdlib.h>
  #include <string.h>
  #include <wchar.h>

  int main(void) {
      wchar_t *wsList;
      wchar_t *wsToken;
      wchar_t *wsCodes;

      wsList  = (wchar_t *)calloc(80,sizeof(wchar_t));
      wsCodes = (wchar_t *)calloc(10,sizeof(wchar_t));
      wsToken = (wchar_t *)calloc(80,sizeof(wchar_t));

      mbstowcs(wsList, "abc,def.ghi;jk!lmnop",25);
      mbstowcs(wsCodes, ";,!.\0",5);

      /* the wide-character string pointed to by wsList is broken up
      into the tokens "abc", "def", "ghi", "jk" and "lmnop" ;
      the null terminator (\0) is encountered and execution stops    */

      wsToken = wcstok(wsList,wsCodes);

      do {
        printf("Token: %S\n", wsToken);
        wsToken = wcstok(NULL,wsCodes);
        } while (wsToken != NULL);

      free(wsList);
      free(wsCodes);
      free(wsToken);
      }

  /************************************************************************

  Output

  Token: abc
  Token: def
  Token: ghi
  Token: jk
  Token: lmnop

  ************************************************************************/

 Using a loop, the following example gathers tokens, deliminated by commas,
 periods, semi-colons, or exclamation points, from  a string until no tokens
 are left.  After processing the example returns the pointers to the tokens
 abc, def, ghi, jk and lmnop. The next call to wcstok returns NULL and the loop
 ends.


ΓòÉΓòÉΓòÉ 11.14. WCSWCS -- Locate wide-character substring ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

wchar_t *wcswcs(const wchar_t *string1, const wchar_t *string2);

Description.

The wcswcs function locates the first occurrence in the string pointed to by
string1 of the sequence of wchar_t characters (excluding the terminating
wchar_t null character) in the string pointed to by string2.

The wcswcs function returns a pointer to the located string or NULL if the
string is not found.  If string2 points to a string with zero length, the
function returns string1.
Related Information

   o  wcschr  - Search wchar_t String for Given wchar_t
   o  wcscspn  - Find Offset of First wchar_t Match
   o  wcspbrk  - Locate wchar_t Characters in String
   o  wcsrchr  - Locate wchar_t Character in String
   o  wcsspn  - Search wchar_t Characters in String
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define SIZE 40

  int main(void) {
      wchar_t buffer1[SIZE];
      wchar_t * ptr;
      wchar_t wch[SIZE];

      mbstowcs(buffer1,"ski slope",SIZE);
      mbstowcs(wch,"sl",SIZE);

      ptr = wcswcs( buffer1, wch );
      printf( "The first occurrence of %S in '%S' is '%S'\n", wch, buffer1, ptr );
      }
  /****************  Output should be similar to:  ******************

  The first occurrence of sl in 'ski slope' is 'slope'

  *******************************************************************/

 This example finds the first occurrence of the wide character string pr in
 buffer1.


ΓòÉΓòÉΓòÉ 11.15. WCSWIDTH -- Determines the display width of wide character strings ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int wcswidth(const wchar_t *pwcs, size_t n);

Description

The wcswidth subroutine determines the number of display columns to be
occupied by the number of wide characters specified by the n parameter in the
string pointed to by the pwcs parameter.  The LC_CTYPE category affects the
behavior of the wcswidth  subroutine.  Fewer than the number of wide characters
specified by the n parameter are counted if a null character is encountered
first.  The wcswidth subroutine returns the number of display columns to be
occupied by the number of wide characters (up to the terminat ing wide
character null) specified by the n parameter (or fewer) in the string pointed
to by the pwcs parameter.  A value of zero is returned if the pwcs parameter is
a wide character null pointer or a pointer to a wide character null (that is,
pwcs or *pwcs is null).  If the pwcs parameter points to an unusable wide
character code, -1 is returned.  n Specifies the maximum number of wide
characters whose display width is to be determined.  pwcs Contains a pointer to
the wide character string.
Related Information

   o  wcwidth - Determines the display width of wide characters.
   o  wchar.h - Header file for wide character function prototypes.

 Example

  #include <string.h>
  #include <stdlib.h>
  #include <wchar.h>

  #define  SIZE  80

  int main(void) {
      wchar_t pwcs[SIZE];
      int  retval,
      int  n;

      setlocale(LC_ALL, "");

      /* Let pwcs point to a wide character null terminated
      ** string. Let n be the number of wide characters whose
      ** display column width is to be determined.
      */

      mbstowcs(pwcs,"This is a test string",SIZE);

      retval = wcswidth( pwcs, n );

      if(retval == -1) {
        /* Error handling. Invalid wide character code
        ** encountered in the wide character string pwcs.
        */
        printf("Invalid wide    character code was    incountered in the    wide character    string\n");
        }

      else
        printf("The width of this wide character string \n %S \nis %d\n",pwcs,retval);

      }

 This example finds the display column width of a wide character string.


ΓòÉΓòÉΓòÉ 11.16. WCTYPE -- Define character class ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

char wctype(const char *charclass);

Description

The wctype functions uses the character class names -

 "alnum"    -  for the alpha numeric class.

 "alpha"    -  for the alphabetic only class.

 "cntrl"    -  for the control class.

 "digit"    -  for the digit class.

 "graph"    -  for the graphics character class.

 "lower"    -  for the lower case character class.

 "print"    -  for the printable character class.

 "punct"    -  for the punctuation class.

 "space"    -  for the space character class.

 "upper"    -  for the upper case character class.

 "xdigit"  -  for the digit or alpha character class.

 "blank"    -  for the hexadecimal alpha numeric class.
 to define the values of wctype_t according to the rules of the coded character
 set defined by character type information in the program's locale (LC_CTYPE).
 These values are valid untill changed by a call to setlocale().
 Related Information

   o  iswctype
   o  wchar.h

 Example

  #include <stdio.h>
  #include <wchar.h>

  #define UPPER_LIMIT   0xFF

  int main(void) {
      wint_t ch;

      for ( ch = 0; ch <= UPPER_LIMIT; ++ch ) {
        printf("\n%3d ", ch);
        printf("%#04x ", ch);
        printf("%3s ", iswctype(ch,wctype("alnum"))  ? "AN" : " ");
        printf("%2s ", iswctype(ch,wctype("alpha"))  ? "A"  : " ");
        printf("%2s",  iswctype(ch,wctype("cntrl"))  ? "C"  : " ");
        printf("%2s",  iswctype(ch,wctype("digit"))  ? "D"  : " ");
        printf("%2s",  iswctype(ch,wctype("graph"))  ? "G"  : " ");
        printf("%2s",  iswctype(ch,wctype("lower"))  ? "L"  : " ");
        printf(" %c",  iswctype(ch,wctype("blank"))  ? "B"  : " ");
        printf("%3s",  iswctype(ch,wctype("punct"))  ? "PU" : " ");
        printf("%2s",  iswctype(ch,wctype("space"))  ? "S"  : " ");
        printf("%3s",  iswctype(ch,wctype("print"))  ? "PR" : " ");
        printf("%2s",  iswctype(ch,wctype("upper"))  ? "U"  : " ");
        printf("%2s",  iswctype(ch,wctype("xdigit")) ? "X"  : " ");
        }
      }

 This example analyzes all characters between code 0x0 and code UPPER_LIMIT,
 printing A for alphabetic characters, AN for alphanumerics, U for uppercase, L
 for lowercase, D for digits, X for hexadecimal digits, S for spaces, PU for
 punctuation, PR for printable characters, G for graphics characters, and C for
 control characters. This example prints the code if printable.

 The output of this example is a 256-line table showing the characters from 0
 to 255 that possess the attributes tested.


ΓòÉΓòÉΓòÉ 11.17. WCWIDTH -- Determines the display width of wide characters ΓòÉΓòÉΓòÉ


Syntax

#include <wchar.h>

int wcwidth(wint_t wc);

Description

The wcwidth subroutine determines the number of display columns to be occupied
by the wide character specified by the wc parameter.  The LC_CTYPE subroutine
affects the behavior of the wcwidth subroutine.  The wcwidth subroutine returns
the number of display columns to be occupied by the WC parameter.  If the WC
parameter is a wide character null, a value of 0 is returned.  If the WC
parameter points to an unusable wide character code, -1 is returned.  wc
Specifies a wide character.
Related Information

   o  wcswidth
   o  wchar.h

 Example

  #include <stdlib.h>
  #include <string.h>
  #include <wchar.h>

  int main(void) {
      wchar_t wc = 0x41;
      int   retval;

      setlocale(LC_ALL, "");

      /* Let wc be the wide character whose
      ** display width is to be found.
      */
      retval= wcwidth( wc );

      if(retval == -1) {
        /*
        ** Error handling. Invalid wide character in wc.
        */
        printf("Invalid wide character\n");
        }
      else
        printf("The width of the wide character\n%C\nis %d\n",wc,retval);
      }

 This example finds the display column width of a wide character.