This commit was manufactured by cvs2svn to create tag 'cygwin-cygwin-1_7_19-release

1_7_19-release'.

Sprout from cygwin-64bit-premerge-branch 2013-04-22 17:11:23 UTC cvs2svn 'This commit was manufactured by cvs2svn to create branch 'cygwin-64bit-'
Cherrypick from master 2013-06-05 07:57:39 UTC Corinna Vinschen <corinna@vinschen.de> '	* faq-programming.xml: Convert url to refer to new flat faq.html file.':
    COPYING.NEWLIB
    ChangeLog
    config.guess
    config.sub
    config/ChangeLog
    config/bootstrap-asan.mk
    config/dfp.m4
    config/picflag.m4
    include/ChangeLog
    include/elf/ChangeLog
    include/elf/aarch64.h
    include/elf/common.h
    include/elf/mips.h
    include/elf/msp430.h
    include/opcode/ChangeLog
    include/opcode/avr.h
    include/opcode/mips.h
    include/opcode/msp430.h
    newlib/ChangeLog
    newlib/MAINTAINERS
    newlib/configure
    newlib/configure.host
    newlib/configure.in
    newlib/libc/configure
    newlib/libc/configure.in
    newlib/libc/ctype/ctype_.c
    newlib/libc/ctype/isalnum.c
    newlib/libc/ctype/isalpha.c
    newlib/libc/ctype/isblank.c
    newlib/libc/ctype/iscntrl.c
    newlib/libc/ctype/isdigit.c
    newlib/libc/ctype/islower.c
    newlib/libc/ctype/isprint.c
    newlib/libc/ctype/ispunct.c
    newlib/libc/ctype/isxdigit.c
    newlib/libc/include/machine/ieeefp.h
    newlib/libc/include/machine/setjmp.h
    newlib/libc/include/reent.h
    newlib/libc/include/sys/cdefs.h
    newlib/libc/include/sys/config.h
    newlib/libc/include/sys/features.h
    newlib/libc/include/sys/reent.h
    newlib/libc/include/sys/stat.h
    newlib/libc/libc.texinfo
    newlib/libc/machine/arm/Makefile.am
    newlib/libc/machine/arm/Makefile.in
    newlib/libc/machine/arm/memcpy-armv7a.S
    newlib/libc/machine/arm/memcpy-armv7m.S
    newlib/libc/machine/arm/memcpy-stub.c
    newlib/libc/machine/arm/memcpy.S
    newlib/libc/machine/arm/strcmp.S
    newlib/libc/machine/configure
    newlib/libc/machine/configure.in
    newlib/libc/machine/powerpc/Makefile.am
    newlib/libc/machine/powerpc/Makefile.in
    newlib/libc/reent/reent.c
    newlib/libc/stdio/fgetc.c
    newlib/libc/stdio/fgetwc.c
    newlib/libc/stdio/fgetws.c
    newlib/libc/stdio/findfp.c
    newlib/libc/stdio/fputc.c
    newlib/libc/stdio/fputwc.c
    newlib/libc/stdio/fputws.c
    newlib/libc/stdio/getc.c
    newlib/libc/stdio/getchar.c
    newlib/libc/stdio/local.h
    newlib/libc/stdio/putc.c
    newlib/libc/stdio/putchar.c
    newlib/libc/stdio/scanf.c
    newlib/libc/stdio/setvbuf.c
    newlib/libc/stdio/ungetwc.c
    newlib/libc/stdio/vfscanf.c
    newlib/libc/stdio/vfwscanf.c
    newlib/libc/stdio/viprintf.c
    newlib/libc/stdio/viscanf.c
    newlib/libc/stdio/vprintf.c
    newlib/libc/stdio/vscanf.c
    newlib/libc/stdio/vwprintf.c
    newlib/libc/stdio/vwscanf.c
    newlib/libc/stdio/wscanf.c
    newlib/libc/stdlib/Makefile.am
    newlib/libc/stdlib/Makefile.in
    newlib/libc/stdlib/__atexit.c
    newlib/libc/stdlib/__call_atexit.c
    newlib/libc/stdlib/ecvtbuf.c
    newlib/libc/stdlib/mblen.c
    newlib/libc/stdlib/mbrlen.c
    newlib/libc/stdlib/mbrtowc.c
    newlib/libc/stdlib/mbtowc.c
    newlib/libc/stdlib/nano-mallocr.c
    newlib/libc/stdlib/rand.c
    newlib/libc/stdlib/strtod.c
    newlib/libc/stdlib/wcrtomb.c
    newlib/libc/stdlib/wctob.c
    newlib/libc/stdlib/wctomb.c
    newlib/libc/string/strtok.c
    newlib/libc/time/asctime.c
    newlib/libc/time/gmtime.c
    newlib/libc/time/lcltime.c
    newlib/libm/libm.texinfo
    winsup/cygserver/ChangeLog
    winsup/cygserver/ChangeLog.64bit
    winsup/cygserver/Makefile.in
    winsup/cygserver/bsd_helper.cc
    winsup/cygserver/bsd_helper.h
    winsup/cygserver/bsd_log.cc
    winsup/cygserver/bsd_log.h
    winsup/cygserver/bsd_mutex.cc
    winsup/cygserver/client.cc
    winsup/cygserver/cygserver.cc
    winsup/cygserver/msg.cc
    winsup/cygserver/process.h
    winsup/cygserver/sem.cc
    winsup/cygserver/shm.cc
    winsup/cygserver/sysv_shm.cc
    winsup/cygserver/threaded_queue.h
    winsup/cygwin/ChangeLog
    winsup/cygwin/ChangeLog.64bit
    winsup/cygwin/Makefile.in
    winsup/cygwin/aclocal.m4
    winsup/cygwin/advapi32.cc
    winsup/cygwin/autoload.cc
    winsup/cygwin/automode.c
    winsup/cygwin/binmode.c
    winsup/cygwin/child_info.h
    winsup/cygwin/common.din
    winsup/cygwin/configure
    winsup/cygwin/configure.ac
    winsup/cygwin/cpuid.h
    winsup/cygwin/cygerrno.h
    winsup/cygwin/cygheap.cc
    winsup/cygwin/cygheap.h
    winsup/cygwin/cygmagic
    winsup/cygwin/cygmalloc.h
    winsup/cygwin/cygserver.h
    winsup/cygwin/cygserver_ipc.h
    winsup/cygwin/cygthread.cc
    winsup/cygwin/cygtls.cc
    winsup/cygwin/cygtls.h
    winsup/cygwin/cygwin.sc.in
    winsup/cygwin/dcrt0.cc
    winsup/cygwin/debug.h
    winsup/cygwin/devices.cc
    winsup/cygwin/devices.h
    winsup/cygwin/devices.in
    winsup/cygwin/dir.cc
    winsup/cygwin/dlfcn.cc
    winsup/cygwin/dll_init.cc
    winsup/cygwin/dll_init.h
    winsup/cygwin/dtable.cc
    winsup/cygwin/environ.cc
    winsup/cygwin/environ.h
    winsup/cygwin/errno.cc
    winsup/cygwin/exception.h
    winsup/cygwin/exceptions.cc
    winsup/cygwin/external.cc
    winsup/cygwin/fcntl.cc
    winsup/cygwin/fenv.cc
    winsup/cygwin/fhandler.cc
    winsup/cygwin/fhandler.h
    winsup/cygwin/fhandler_clipboard.cc
    winsup/cygwin/fhandler_console.cc
    winsup/cygwin/fhandler_dev.cc
    winsup/cygwin/fhandler_disk_file.cc
    winsup/cygwin/fhandler_dsp.cc
    winsup/cygwin/fhandler_fifo.cc
    winsup/cygwin/fhandler_floppy.cc
    winsup/cygwin/fhandler_mailslot.cc
    winsup/cygwin/fhandler_mem.cc
    winsup/cygwin/fhandler_netdrive.cc
    winsup/cygwin/fhandler_proc.cc
    winsup/cygwin/fhandler_process.cc
    winsup/cygwin/fhandler_procnet.cc
    winsup/cygwin/fhandler_procsys.cc
    winsup/cygwin/fhandler_procsysvipc.cc
    winsup/cygwin/fhandler_random.cc
    winsup/cygwin/fhandler_raw.cc
    winsup/cygwin/fhandler_registry.cc
    winsup/cygwin/fhandler_serial.cc
    winsup/cygwin/fhandler_socket.cc
    winsup/cygwin/fhandler_tape.cc
    winsup/cygwin/fhandler_termios.cc
    winsup/cygwin/fhandler_tty.cc
    winsup/cygwin/fhandler_virtual.cc
    winsup/cygwin/fhandler_virtual.h
    winsup/cygwin/fhandler_windows.cc
    winsup/cygwin/fhandler_zero.cc
    winsup/cygwin/flock.cc
    winsup/cygwin/fork.cc
    winsup/cygwin/gendef
    winsup/cygwin/gentls_offsets
    winsup/cygwin/glob.cc
    winsup/cygwin/globals.cc
    winsup/cygwin/grp.cc
    winsup/cygwin/heap.cc
    winsup/cygwin/hookapi.cc
    winsup/cygwin/i686.din
    winsup/cygwin/include/a.out.h
    winsup/cygwin/include/asm/byteorder.h
    winsup/cygwin/include/bits/wordsize.h
    winsup/cygwin/include/cygwin/acl.h
    winsup/cygwin/include/cygwin/config.h
    winsup/cygwin/include/cygwin/cygwin_dll.h
    winsup/cygwin/include/cygwin/grp.h
    winsup/cygwin/include/cygwin/if.h
    winsup/cygwin/include/cygwin/ipc.h
    winsup/cygwin/include/cygwin/msg.h
    winsup/cygwin/include/cygwin/sem.h
    winsup/cygwin/include/cygwin/shm.h
    winsup/cygwin/include/cygwin/signal.h
    winsup/cygwin/include/cygwin/socket.h
    winsup/cygwin/include/cygwin/stat.h
    winsup/cygwin/include/cygwin/stdlib.h
    winsup/cygwin/include/cygwin/sysproto.h
    winsup/cygwin/include/cygwin/time.h
    winsup/cygwin/include/cygwin/types.h
    winsup/cygwin/include/cygwin/version.h
    winsup/cygwin/include/fcntl.h
    winsup/cygwin/include/fts.h
    winsup/cygwin/include/ftw.h
    winsup/cygwin/include/glob.h
    winsup/cygwin/include/inttypes.h
    winsup/cygwin/include/io.h
    winsup/cygwin/include/limits.h
    winsup/cygwin/include/mntent.h
    winsup/cygwin/include/stdint.h
    winsup/cygwin/include/sys/cygwin.h
    winsup/cygwin/include/sys/dirent.h
    winsup/cygwin/include/sys/resource.h
    winsup/cygwin/include/sys/socket.h
    winsup/cygwin/include/sys/strace.h
    winsup/cygwin/init.cc
    winsup/cygwin/ioctl.cc
    winsup/cygwin/ipc.cc
    winsup/cygwin/kernel32.cc
    winsup/cygwin/lc_msg.h
    winsup/cygwin/lib/_cygwin_crt0_common.cc
    winsup/cygwin/lib/crt0.h
    winsup/cygwin/lib/cygwin_attach_dll.c
    winsup/cygwin/lib/premain0.c
    winsup/cygwin/lib/premain1.c
    winsup/cygwin/lib/premain2.c
    winsup/cygwin/lib/premain3.c
    winsup/cygwin/libc/arc4random.cc
    winsup/cygwin/libc/base64.c
    winsup/cygwin/libc/bsdlib.cc
    winsup/cygwin/libc/fts.c
    winsup/cygwin/libc/ftw.c
    winsup/cygwin/libc/inet_network.c
    winsup/cygwin/libc/minires-os-if.c
    winsup/cygwin/libc/minires.c
    winsup/cygwin/libc/nftw.c
    winsup/cygwin/libc/rcmd.cc
    winsup/cygwin/libc/rexec.cc
    winsup/cygwin/libstdcxx_wrapper.cc
    winsup/cygwin/localtime.cc
    winsup/cygwin/malloc_wrapper.cc
    winsup/cygwin/miscfuncs.cc
    winsup/cygwin/mkimport
    winsup/cygwin/mktemp.cc
    winsup/cygwin/mmap.cc
    winsup/cygwin/mount.cc
    winsup/cygwin/mount.h
    winsup/cygwin/msg.cc
    winsup/cygwin/mtinfo.h
    winsup/cygwin/net.cc
    winsup/cygwin/netdb.cc
    winsup/cygwin/nfs.h
    winsup/cygwin/nlsfuncs.cc
    winsup/cygwin/ntdll.h
    winsup/cygwin/ntea.cc
    winsup/cygwin/passwd.cc
    winsup/cygwin/path.cc
    winsup/cygwin/path.h
    winsup/cygwin/perprocess.h
    winsup/cygwin/pinfo.cc
    winsup/cygwin/pinfo.h
    winsup/cygwin/pipe.cc
    winsup/cygwin/poll.cc
    winsup/cygwin/posix.sgml
    winsup/cygwin/posix_ipc.cc
    winsup/cygwin/profil.c
    winsup/cygwin/profil.h
    winsup/cygwin/pseudo-reloc.cc
    winsup/cygwin/pwdgrp.h
    winsup/cygwin/regex/engine.c
    winsup/cygwin/regex/regcomp.c
    winsup/cygwin/registry.cc
    winsup/cygwin/regparm.h
    winsup/cygwin/release/1.7.19
    winsup/cygwin/resource.cc
    winsup/cygwin/sched.cc
    winsup/cygwin/sec_acl.cc
    winsup/cygwin/sec_auth.cc
    winsup/cygwin/sec_helper.cc
    winsup/cygwin/security.cc
    winsup/cygwin/security.h
    winsup/cygwin/select.cc
    winsup/cygwin/select.h
    winsup/cygwin/sem.cc
    winsup/cygwin/shared.cc
    winsup/cygwin/shared_info.h
    winsup/cygwin/shm.cc
    winsup/cygwin/signal.cc
    winsup/cygwin/sigproc.cc
    winsup/cygwin/sigproc.h
    winsup/cygwin/smallprint.cc
    winsup/cygwin/spawn.cc
    winsup/cygwin/speclib
    winsup/cygwin/spinlock.h
    winsup/cygwin/strace.cc
    winsup/cygwin/strfuncs.cc
    winsup/cygwin/strsig.cc
    winsup/cygwin/sync.cc
    winsup/cygwin/sync.h
    winsup/cygwin/syscalls.cc
    winsup/cygwin/sysconf.cc
    winsup/cygwin/syslog.cc
    winsup/cygwin/termios.cc
    winsup/cygwin/textmode.c
    winsup/cygwin/textreadmode.c
    winsup/cygwin/thread.cc
    winsup/cygwin/thread.h
    winsup/cygwin/timer.cc
    winsup/cygwin/times.cc
    winsup/cygwin/tlsoffsets.h
    winsup/cygwin/tlsoffsets64.h
    winsup/cygwin/tty.cc
    winsup/cygwin/tty.h
    winsup/cygwin/uinfo.cc
    winsup/cygwin/wait.cc
    winsup/cygwin/winbase.h
    winsup/cygwin/wincap.cc
    winsup/cygwin/wincap.h
    winsup/cygwin/window.cc
    winsup/cygwin/winlean.h
    winsup/cygwin/winsup.h
    winsup/cygwin/wow64.cc
    winsup/cygwin/wow64.h
    winsup/cygwin/x86_64.din
    winsup/doc/.cvsignore
    winsup/doc/ChangeLog
    winsup/doc/Makefile.in
    winsup/doc/Wishlist
    winsup/doc/bodysnatcher.pl
    winsup/doc/configure
    winsup/doc/configure.ac
    winsup/doc/cygserver.xml
    winsup/doc/cygwin-api.in.xml
    winsup/doc/cygwin-ug-net.xml
    winsup/doc/cygwin.xsl
    winsup/doc/cygwinenv.xml
    winsup/doc/dll.xml
    winsup/doc/effectively.xml
    winsup/doc/faq-api.xml
    winsup/doc/faq-copyright.xml
    winsup/doc/faq-programming.xml
    winsup/doc/faq-resources.xml
    winsup/doc/faq-setup.xml
    winsup/doc/faq-using.xml
    winsup/doc/faq-what.xml
    winsup/doc/faq.xml
    winsup/doc/filemodes.xml
    winsup/doc/gcc.xml
    winsup/doc/gdb.xml
    winsup/doc/highlights.xml
    winsup/doc/legal.xml
    winsup/doc/new-features.xml
    winsup/doc/ntsec.xml
    winsup/doc/ov-ex-unix.xml
    winsup/doc/ov-ex-win.xml
    winsup/doc/overview.xml
    winsup/doc/pathnames.xml
    winsup/doc/programming.xml
    winsup/doc/setup-env.xml
    winsup/doc/setup-files.xml
    winsup/doc/setup-locale.xml
    winsup/doc/setup-maxmem.xml
    winsup/doc/setup-net.xml
    winsup/doc/specialnames.xml
    winsup/doc/textbinary.xml
    winsup/doc/ug-info.xml
    winsup/doc/using.xml
    winsup/doc/windres.xml
    winsup/doc/xidepend
    winsup/lsaauth/ChangeLog
    winsup/lsaauth/ChangeLog.64bit
    winsup/lsaauth/Makefile.in
    winsup/lsaauth/configure
    winsup/lsaauth/configure.ac
    winsup/utils/ChangeLog
    winsup/utils/ChangeLog.64bit
    winsup/utils/Makefile.in
    winsup/utils/aclocal.m4
    winsup/utils/configure
    winsup/utils/cygcheck.cc
    winsup/utils/dumper.cc
    winsup/utils/dumper.h
    winsup/utils/kill.cc
    winsup/utils/ldd.cc
    winsup/utils/locale.cc
    winsup/utils/mkgroup.c
    winsup/utils/mkpasswd.c
    winsup/utils/module_info.cc
    winsup/utils/mount.cc
    winsup/utils/parse_pe.cc
    winsup/utils/passwd.c
    winsup/utils/path.cc
    winsup/utils/ps.cc
    winsup/utils/regtool.cc
    winsup/utils/ssp.c
    winsup/utils/strace.cc
    winsup/utils/tzset.c
    winsup/utils/utils.xml
Delete:
    COPYING3
    COPYING3.LIB
    config.rpath
    configure.ac
    ltgcc.m4
    newlib/libc/machine/aarch64/Makefile.am
    newlib/libc/machine/aarch64/Makefile.in
    newlib/libc/machine/aarch64/aclocal.m4
    newlib/libc/machine/aarch64/configure
    newlib/libc/machine/aarch64/configure.in
    newlib/libc/machine/aarch64/memcmp-stub.c
    newlib/libc/machine/aarch64/memcmp.S
    newlib/libc/machine/aarch64/memcpy-stub.c
    newlib/libc/machine/aarch64/memcpy.S
    newlib/libc/machine/aarch64/memmove-stub.c
    newlib/libc/machine/aarch64/memmove.S
    newlib/libc/machine/aarch64/memset-stub.c
    newlib/libc/machine/aarch64/memset.S
    newlib/libc/machine/aarch64/setjmp.S
    newlib/libc/machine/aarch64/strcmp-stub.c
    newlib/libc/machine/aarch64/strcmp.S
    newlib/libc/machine/aarch64/strlen-stub.c
    newlib/libc/machine/aarch64/strlen.S
    newlib/libc/machine/aarch64/strncmp-stub.c
    newlib/libc/machine/aarch64/strncmp.S
    newlib/libc/machine/aarch64/strnlen-stub.c
    newlib/libc/machine/aarch64/strnlen.S
    newlib/libc/machine/epiphany/Makefile.am
    newlib/libc/machine/epiphany/Makefile.in
    newlib/libc/machine/epiphany/aclocal.m4
    newlib/libc/machine/epiphany/configure
    newlib/libc/machine/epiphany/configure.in
    newlib/libc/machine/epiphany/machine/stdlib.h
    newlib/libc/machine/epiphany/setjmp.S
    newlib/libc/machine/powerpc/times.c
    newlib/libc/sys/epiphany/Makefile.am
    newlib/libc/sys/epiphany/Makefile.in
    newlib/libc/sys/epiphany/aclocal.m4
    newlib/libc/sys/epiphany/configure
    newlib/libc/sys/epiphany/configure.in
    newlib/libc/sys/epiphany/e_printf.c
    newlib/libm/machine/aarch64/Makefile.am
    newlib/libm/machine/aarch64/Makefile.in
    newlib/libm/machine/aarch64/aclocal.m4
    newlib/libm/machine/aarch64/configure
    newlib/libm/machine/aarch64/configure.in
    newlib/libm/machine/aarch64/s_ceil.c
    newlib/libm/machine/aarch64/s_floor.c
    newlib/libm/machine/aarch64/s_fma.c
    newlib/libm/machine/aarch64/s_fmax.c
    newlib/libm/machine/aarch64/s_fmin.c
    newlib/libm/machine/aarch64/s_llrint.c
    newlib/libm/machine/aarch64/s_llround.c
    newlib/libm/machine/aarch64/s_lrint.c
    newlib/libm/machine/aarch64/s_lround.c
    newlib/libm/machine/aarch64/s_nearbyint.c
    newlib/libm/machine/aarch64/s_rint.c
    newlib/libm/machine/aarch64/s_round.c
    newlib/libm/machine/aarch64/s_trunc.c
    newlib/libm/machine/aarch64/sf_ceil.c
    newlib/libm/machine/aarch64/sf_floor.c
    newlib/libm/machine/aarch64/sf_fma.c
    newlib/libm/machine/aarch64/sf_fmax.c
    newlib/libm/machine/aarch64/sf_fmin.c
    newlib/libm/machine/aarch64/sf_llrint.c
    newlib/libm/machine/aarch64/sf_llround.c
    newlib/libm/machine/aarch64/sf_lrint.c
    newlib/libm/machine/aarch64/sf_lround.c
    newlib/libm/machine/aarch64/sf_nearbyint.c
    newlib/libm/machine/aarch64/sf_rint.c
    newlib/libm/machine/aarch64/sf_round.c
    newlib/libm/machine/aarch64/sf_trunc.c
    winsup/cygwin/cygwin.din
    winsup/cygwin/cygwin.sc
    winsup/doc/cygserver.sgml
    winsup/doc/cygwin-api.in.sgml
    winsup/doc/cygwin-ug-net.in.sgml
    winsup/doc/cygwin-ug.in.sgml
    winsup/doc/cygwin.dsl
    winsup/doc/cygwinenv.sgml
    winsup/doc/dll.sgml
    winsup/doc/effectively.sgml
    winsup/doc/faq-sections.xml
    winsup/doc/filemodes.sgml
    winsup/doc/gcc.sgml
    winsup/doc/gdb.sgml
    winsup/doc/legal.sgml
    winsup/doc/new-features.sgml
    winsup/doc/ntsec.sgml
    winsup/doc/overview.sgml
    winsup/doc/overview2.sgml
    winsup/doc/pathnames.sgml
    winsup/doc/programming.sgml
    winsup/doc/setup-net.sgml
    winsup/doc/setup.sgml
    winsup/doc/setup2.sgml
    winsup/doc/textbinary.sgml
    winsup/doc/using.sgml
    winsup/doc/windres.sgml
    winsup/utils/utils.sgml

1 files changed, 432 insertions, 0 deletions

diff --git a/winsup/doc/setup-locale.xml b/winsup/doc/setup-locale.xml
new file mode 100644
index 000000000..de0532f62
--- /dev/null
+++ b/winsup/doc/setup-locale.xml
@@ -0,0 +1,432 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="setup-locale"><title>Internationalization</title>
+
+<sect2 id="setup-locale-ov"><title>Overview</title>
+
+<para>
+Internationalization support is controlled by the <envar>LANG</envar> and
+<envar>LC_xxx</envar> environment variables.  You can set all of them
+but Cygwin itself only honors the variables <envar>LC_ALL</envar>,
+<envar>LC_CTYPE</envar>, and <envar>LANG</envar>, in this order, according
+to the POSIX standard.  The content of these variables should follow the
+POSIX standard for a locale specifier.  The correct form of a locale
+specifier is</para>
+
+<screen>
+  language[[_TERRITORY][.charset][@modifier]]
+</screen>
+
+<para>"language" is a lowercase two character string per ISO 639-1, or,
+if there is no ISO 639-1 code for the language (for instance, "Lower Sorbian"),
+a three character string per ISO 639-3.</para>
+
+<para>"TERRITORY" is an uppercase two character string per ISO 3166, charset is
+one of a list of supported character sets.  The modifier doesn't matter
+here (though some are recognized, see below).  If you're interested in the
+exact description, you can find it in the online publication of the POSIX
+manual pages on the homepage of the
+<ulink url="http://www.opengroup.org/">Open Group</ulink>.</para>
+
+<para>Typical locale specifiers are</para>
+
+<screen>
+  "de_CH"	   language = German, territory = Switzerland, default charset
+  "fr_FR.UTF-8"    language = french, territory = France, charset = UTF-8
+  "ko_KR.eucKR"    language = korean, territory = South Korea, charset = eucKR
+  "syr_SY"         language = Syriac, territory = Syria, default charset
+</screen>
+
+<para>
+If the locale specifier does not follow the above form, Cygwin checks
+if the locale is one of the locale aliases defined in the file
+<filename>/usr/share/locale/locale.alias</filename>.  If so, and if
+the replacement localename is supported by the underlying Windows,
+the locale is accepted, too.  So, given the default content of the
+<filename>/usr/share/locale/locale.alias</filename> file, the below
+examples would be valid locale specifiers as well.
+</para>
+
+<screen>
+  "catalan"        defined as "ca_ES.ISO-8859-1" in locale.alias
+  "japanese"       defined as "ja_JP.eucJP"      in locale.alias
+  "turkish"        defined as "tr_TR.ISO-8859-9" in locale.alias
+</screen>
+
+<para>The file <filename>/usr/share/locale/locale.alias</filename> is
+provided by the gettext package under Cygwin.</para>
+
+<para>
+At application startup, the application's locale is set to the default
+"C" or "POSIX" locale.  Under Cygwin 1.7.2 and later, this locale defaults
+to the ASCII character set on the application level.  If you want to stick
+to the "C" locale and only change to another charset, you can define this
+by setting one of the locale environment variables to "C.charset".  For
+instance</para>
+
+<screen>
+  "C.ISO-8859-1"
+</screen>
+
+<note><para>The default locale in the absence of the aforementioned locale
+environment variables is "C.UTF-8".</para></note>
+
+<para>Windows uses the UTF-16 charset exclusively to store the names
+of any object used by the Operating System.  This is especially important
+with filenames.  Cygwin uses the setting of the locale environment variables
+<envar>LC_ALL</envar>, <envar>LC_CTYPE</envar>, and <envar>LANG</envar>, to
+determine how to convert Windows filenames from their UTF-16 representation
+to the singlebyte or multibyte character set used by Cygwin.</para>
+
+<para>
+The setting of the locale environment variables at process startup
+is effective for Cygwin's internal conversions to and from the Windows UTF-16
+object names for the entire lifetime of the current process.  Changing
+the environment variables to another value changes the way filenames are
+converted in subsequently started child processes, but not within the same
+process.</para>
+
+<para>
+However, even if one of the locale environment variables is set to
+some other value than "C", this does <emphasis>only</emphasis> affect
+how Cygwin itself converts filenames.  As the POSIX standard requires,
+it's the application's responsibility to activate that locale for its
+own purposes, typically by using the call</para>
+
+<screen>
+  setlocale (LC_ALL, "");
+</screen>
+
+<para>early in the application code.  Again, so that this doesn't get
+lost:  If the application calls setlocale as above, and there is none
+of the important locale variables set in the environment, the locale
+is set to the default locale, which is "C.UTF-8".</para>
+
+<para>But what about applications which are not locale-aware?  Per POSIX,
+they are running in the "C" or "POSIX" locale, which implies the ASCII
+charset.  The Cygwin DLL itself, however, will nevertheless use the locale
+set in the environment (or the "C.UTF-8" default locale) for converting
+filenames etc.</para>
+
+<para>When the locale in the environment specifies an ASCII charset,
+for example "C" or "en_US.ASCII", Cygwin will still use UTF-8
+under the hood to translate filenames.  This allows for easier
+interoperability with applications running in the default "C.UTF-8" locale.
+</para>
+
+<para>
+Starting with Cygwin 1.7.2, the language and territory are used to
+fetch locale-dependent information from Windows.  If the language and
+territory are not known to Windows, the <function>setlocale</function>
+function fails.</para>
+
+<para>The following modifiers are recognized.  Any other modifier is simply
+ignored for now.</para>
+
+<itemizedlist mark="bullet">
+
+<listitem><para>
+For locales which use the Euro (EUR) as currency, the modifier "@euro"
+can be added to enforce usage of the ISO-8859-15 character set, which
+includes a character for the "Euro" currency sign.
+</para></listitem>
+
+<listitem><para>
+The default script used for all Serbian language locales (sr_BA, sr_ME, sr_RS,
+and the deprecated sr_CS and sr_SP) is cyrillic.  With the "@latin" modifier
+it gets switched to the latin script with the respective collation behaviour.
+</para></listitem>
+
+<listitem><para>
+The default charset of the "be_BY" locale (Belarusian/Belarus) is CP1251.
+With the "@latin" modifier it's UTF-8.
+</para></listitem>
+
+<listitem><para>
+The default charset of the "tt_RU" locale (Tatar/Russia) is ISO-8859-5.
+With the "@iqtelif" modifier it's UTF-8.
+</para></listitem>
+
+<listitem><para>
+The default charset of the "uz_UZ" locale (Uzbek/Uzbekistan) is ISO-8859-1.
+With the "@cyrillic" modifier it's UTF-8.
+</para></listitem>
+
+<listitem><para>
+There's a class of characters in the Unicode character set, called the
+"CJK Ambiguous Width" characters.  For these characters, the width
+returned by the wcwidth/wcswidth functions is usually 1.  This can be a
+problem with East-Asian languages, which historically use character sets
+where these characters have a width of 2.  Therefore, wcwidth/wcswidth
+return 2 as the width of these characters when an East-Asian charset such
+as GBK or SJIS is selected, or when UTF-8 is selected and the language is
+specified as "zh" (Chinese), "ja" (Japanese), or "ko" (Korean).  This is
+not correct in all circumstances, hence the locale modifier "@cjknarrow"
+can be used to force wcwidth/wcswidth to return 1 for the ambiguous width
+characters.
+</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="setup-locale-how"><title>How to set the locale</title>
+
+<itemizedlist mark="bullet">
+
+<listitem><para>
+Assume that you've set one of the aforementioned environment variables to some
+valid POSIX locale value, other than "C" and "POSIX".  Assume further that
+you're living in Japan.  You might want to use the language code "ja" and the
+territory "JP", thus setting, say, <envar>LANG</envar> to "ja_JP".  You didn't
+set a character set, so what will Cygwin use now?  Starting with Cygwin 1.7.2,
+the default character set is determined by the default Windows ANSI codepage
+for this language and territory.  Cygwin uses a character set which is the
+typical Unix-equivalent to the Windows ANSI codepage.  For instance:</para>
+
+<screen>
+  "en_US"		ISO-8859-1
+  "el_GR"		ISO-8859-7
+  "pl_PL"		ISO-8859-2
+  "pl_PL@euro"		ISO-8859-15
+  "ja_JP"		EUCJP
+  "ko_KR"		EUCKR
+  "te_IN"		UTF-8
+</screen>
+</listitem>
+
+<listitem><para>
+You don't want to use the default character set?  In that case you have to
+specify the charset explicitly.  For instance, assume you're from Japan and
+don't want to use the japanese default charset EUC-JP, but the Windows
+default charset SJIS.  What you can do, for instance, is to set the
+<envar>LANG</envar> variable in the <command>mintty</command> Cygwin Terminal
+in the "Text" section of its "Options" dialog.  If you're starting your
+Cygwin session via a batch file or a shortcut to a batch file, you can also
+just set LANG there:</para>
+
+<screen>
+  @echo off
+
+  C:
+  chdir C:\cygwin\bin
+  set LANG=ja_JP.SJIS
+  bash --login -i
+</screen>
+
+<note><para>For a list of locales supported by your Windows machine, use the new
+<command>locale -a</command> command, which is part of the Cygwin package.
+For a description see <xref linkend="locale"></xref></para></note>
+
+<note><para>For a list of supported character sets, see
+<xref linkend="setup-locale-charsetlist"></xref>
+</para></note>
+</listitem>
+
+<listitem><para>
+Last, but not least, most singlebyte or doublebyte charsets have a big
+disadvantage.  Windows filesystems use the Unicode character set in the
+UTF-16 encoding to store filename information.  Not all characters
+from the Unicode character set are available in a singlebyte or doublebyte
+charset.  While Cygwin has a workaround to access files with unusual
+characters (see <xref linkend="pathnames-unusual"></xref>), a better
+workaround is to use always the UTF-8 character set.</para>
+
+<para><emphasis>UTF-8 is the only multibyte character set which can represent
+every Unicode character.</emphasis></para>
+
+<screen>
+  set LANG=es_MX.UTF-8
+</screen>
+
+<para>For a description of the Unicode standard, see the homepage of the
+<ulink url="http://www.unicode.org/">Unicode Consortium</ulink>.
+</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="setup-locale-console"><title>The Windows Console character set</title>
+
+<para>Sometimes the Windows console is used to run Cygwin applications.
+While terminal emulations like the Cygwin Terminal <command>mintty</command>
+or <command>xterm</command> have a distinct way to set the character set
+used for in- and output, the Windows console hasn't such a way, since it's
+not an application in its own right.</para>
+
+<para>This problem is solved in Cygwin as follows.  When a Cygwin
+process is started in a Windows console (either explicitly from cmd.exe,
+or implicitly by, for instance, running the
+<filename>C:\cygwin\Cygwin.bat</filename> batch file), the Console character
+set is determined by the setting of the aforementioned
+internationalization environment variables, the same way as described in
+<xref linkend="setup-locale-how"></xref>.  </para>
+
+<para>What is that good for?  Why not switch the console character set with
+the applications requirements?  After all, the application knows if it uses
+localization or not.  However, what if a non-localized application calls
+a remote application which itself is localized?  This can happen with
+<command>ssh</command> or <command>rlogin</command>.  Both commands don't
+have and don't need localization and they never call
+<function>setlocale</function>.  Setting one of the internationalization
+environment variable to the same charset as the remote machine before
+starting <command>ssh</command> or <command>rlogin</command> fixes that
+problem.</para>
+
+</sect2>
+
+<sect2 id="setup-locale-problems"><title>Potential Problems when using Locales</title>
+
+<para>
+You can set the above internationalization variables not only when
+starting the first Cygwin process, but also in your Cygwin shell on the
+fly, even switch to yet another character set, and yet another.  In bash
+for instance:</para>
+
+<screen>
+  <prompt>bash$</prompt> export LC_CTYPE="nl_BE.UTF-8"
+</screen>
+
+<para>However, here's a problem.  At the start of the first Cygwin process
+in a session, the Windows environment is converted from UTF-16 to UTF-8.
+The environment is another of the system objects stored in UTF-16 in
+Windows.</para>
+
+<para>As long as the environment only contains ASCII characters, this is
+no problem at all.  But if it contains native characters, and you're planning
+to use, say, GBK, the environment will result in invalid characters in
+the GBK charset.  This would be especially a problem in variables like
+<envar>PATH</envar>.  To circumvent the worst problems, Cygwin converts
+the <envar>PATH</envar> environment variable to the charset set in the
+environment, if it's different from the UTF-8 charset.</para>
+
+<note><para>Per POSIX, the name of an environment variable should only
+consist of valid ASCII characters, and only of uppercase letters, digits, and
+the underscore for maximum portability.</para></note>
+
+<para>Symbolic links, too, may pose a problem when switching charsets on
+the fly.  A symbolic link contains the filename of the target file the
+symlink points to.  When a symlink had been created with older versions
+of Cygwin, the current ANSI or OEM character set had been used to store
+the target filename, dependent on the old <envar>CYGWIN</envar>
+environment variable setting <envar>codepage</envar> (see <xref
+linkend="cygwinenv-removed-options"></xref>.  If the target filename
+contains non-ASCII characters and you use another character set than
+your default ANSI/OEM charset, the target filename of the symlink is now
+potentially an invalid character sequence in the new character set.
+This behaviour is not different from the behaviour in other Operating
+Systems.  So, if you suddenly can't access a symlink anymore which
+worked all these years before, maybe it's because you switched to
+another character set.  This doesn't occur with symlinks created with
+Cygwin 1.7 or later.  </para>
+
+<para>Another problem you might encounter is that older versions of
+Windows did not install all charsets by default.  If you are running
+Windows XP or older, you can open the "Regional and Language Options"
+portion of the Control Panel, select the "Advanced" tab, and select
+entries from the "Code page conversion tables" list.  The following
+entries are useful to cygwin: 932/SJIS, 936/GBK, 949/EUC-KR, 950/Big5,
+20932/EUC-JP.</para>
+
+</sect2>
+
+<sect2 id="setup-locale-charsetlist"><title>List of supported character sets</title>
+
+<para>Last but not least, here's the list of currently supported character
+sets.  The left-hand expression is the name of the charset, as you would use
+it in the internationalization environment variables as outlined above.
+Note that charset specifiers are case-insensitive.  <literal>EUCJP</literal>
+is equivalent to <literal>eucJP</literal> or <literal>eUcJp</literal>.
+Writing the charset in the exact case as given in the list below is a
+good convention, though.
+</para>
+
+<para>The right-hand side is the number of the equivalent Windows
+codepage as well as the Windows name of the codepage.  They are only
+noted here for reference.  Don't try to use the bare codepage number or
+the Windows name of the codepage as charset in locale specifiers, unless
+they happen to be identical with the left-hand side.  Especially in case
+of the "CPxxx" style charsets, always use them with the trailing "CP".</para>
+
+<para>This works:</para>
+
+<screen>
+  set LC_ALL=en_US.CP437
+</screen>
+
+<para>This does <emphasis>not</emphasis> work:</para>
+
+<screen>
+  set LC_ALL=en_US.437
+</screen>
+
+<para>You can find a full list of Windows codepages on the Microsoft MSDN page
+<ulink url="http://msdn.microsoft.com/en-us/library/dd317756(VS.85).aspx">Code Page Identifiers</ulink>.</para>
+
+<screen>
+    Charset               Codepage
+    -------------------   -------------------------------------------
+    ASCII                 20127 (US_ASCII)
+
+    CP437                   437 (OEM United States)
+    CP720                   720 (DOS Arabic)
+    CP737                   737 (OEM Greek)
+    CP775                   775 (OEM Baltic)
+    CP850                   850 (OEM Latin 1, Western European)
+    CP852                   852 (OEM Latin 2, Central European)
+    CP855                   855 (OEM Cyrillic)
+    CP857                   857 (OEM Turkish)
+    CP858                   858 (OEM Latin 1 + Euro Symbol)
+    CP862                   862 (OEM Hebrew)
+    CP866                   866 (OEM Russian)
+    CP874                   874 (ANSI/OEM Thai)
+    CP932		    932 (Shift_JIS, not exactly identical to SJIS)
+    CP1125                 1125 (OEM Ukraine)
+    CP1250                 1250 (ANSI Central European)
+    CP1251                 1251 (ANSI Cyrillic)
+    CP1252                 1252 (ANSI Latin 1, Western European)
+    CP1253                 1253 (ANSI Greek)
+    CP1254                 1254 (ANSI Turkish)
+    CP1255                 1255 (ANSI Hebrew)
+    CP1256                 1256 (ANSI Arabic)
+    CP1257                 1257 (ANSI Baltic)
+    CP1258                 1258 (ANSI/OEM Vietnamese)
+
+    ISO-8859-1            28591 (ISO-8859-1)
+    ISO-8859-2            28592 (ISO-8859-2)
+    ISO-8859-3            28593 (ISO-8859-3)
+    ISO-8859-4            28594 (ISO-8859-4)
+    ISO-8859-5            28595 (ISO-8859-5)
+    ISO-8859-6            28596 (ISO-8859-6)
+    ISO-8859-7            28597 (ISO-8859-7)
+    ISO-8859-8            28598 (ISO-8859-8)
+    ISO-8859-9            28599 (ISO-8859-9)
+    ISO-8859-10             -   (not available)
+    ISO-8859-11             -   (not available)
+    ISO-8859-13           28603 (ISO-8859-13)
+    ISO-8859-14             -   (not available)
+    ISO-8859-15           28605 (ISO-8859-15)
+    ISO-8859-16             -   (not available)
+
+    Big5                    950 (ANSI/OEM Traditional Chinese)
+    EUCCN or euc-CN         936 (ANSI/OEM Simplified Chinese)
+    EUCJP or euc-JP       20932 (EUC Japanese)
+    EUCKR or euc-KR         949 (EUC Korean)
+    GB2312                  936 (ANSI/OEM Simplified Chinese)
+    GBK                     936 (ANSI/OEM Simplified Chinese)
+    GEORGIAN-PS             -   (not available)
+    KOI8-R                20866 (KOI8-R Russian Cyrillic)
+    KOI8-U                21866 (KOI8-U Ukrainian Cyrillic)
+    PT154                   -   (not available)
+    SJIS                    -   (not available, almost, but not exactly CP932)
+    TIS620 or TIS-620       874 (ANSI/OEM Thai)
+
+    UTF-8 or utf8         65001 (UTF-8)
+</screen>
+
+</sect2>
+
+</sect1>