mingw-cvs Mailing List for MinGW - Minimalist GNU for Windows

Update of /cvsroot/mingw/catgets
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv14480

Modified Files:
	ChangeLog 
Log Message:
Add manpage sources.


Index: ChangeLog
===================================================================
RCS file: /cvsroot/mingw/catgets/ChangeLog,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -d -r1.15 -r1.16
*** ChangeLog	16 Jul 2007 19:59:42 -0000	1.15
--- ChangeLog	16 Jul 2007 22:16:49 -0000	1.16
***************
*** 1,4 ****
--- 1,29 ----
  2007-07-16  Keith Marshall  <kei...@us...>
  
+ 	Add manpage sources.
+ 
+ 	* man: New directory, containing...
+ 	* man/catopen.man, man/catgets.man, man/catclose.man: New files.
+ 	* man/gencat.man: New file.
+ 
+ 	* Makefile.in (VPATH): Add `man' source directory.
+ 	(MANPAGE_SOURCES): Define; it includes all new `*.man' files, as
+ 	itemised above, for this update.
+ 	(MANSECTS, MAN1EXT, MAN2EXT, MAN3EXT): Define.
+ 	(mansect_lookup, mansect_transform, mansect, manpage): New macros;
+ 	use them to define a generic rule for generating installable manpages,
+ 	from raw manpage source, used by...
+ 	(all-man): this new documentation target.
+ 	(all-info, all-html-doc, all-pdf, all-ps): New documentation targets;
+ 	none invoke any action, at present.
+ 	(all-doc): New collective documentation target; it invokes `all-man',
+ 	`all-info', `all-htmldoc', `all-pdf' and `all-ps'.
+ 	(all): Add `all-doc' as new prerequisite.
+ 	(install-man): Add prerequisites and commands for `MANPAGE_SOURCES'.
+ 	(DISTDIRS): Add `man'.
+ 	(clean): Add `*.n', `*.a' and `*.dll' as generic prototypes for `rm'.
+ 
+ 2007-07-16  Keith Marshall  <kei...@us...>
+ 
  	* catclose.c (mc_close): Error out, if descriptor for message
  	catalogue to be closed lies outside the valid range.

Update of /cvsroot/mingw/catgets/man
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv14480/man

Added Files:
	catclose.man catgets.man catopen.man gencat.man 
Log Message:
Add manpage sources.


--- NEW FILE: catgets.man ---
'\"
.TH catgets @MAN3EXT@ 19-Jun-2007 MinGW "MinGW Programming Reference
.
.SH NAME
.B catgets
\- retrieve message text from a national language catalogue
.
.\" Copyright (C) 2007,  Keith Marshall.
.
.\" Permission is granted to copy, distribute and/or modify this manpage
.\" under the terms of the GNU Free Documentation License, Version 1.2
.\" or any later version published by the Free Software Foundation, with
.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the accompanying file, `FDL'.
.
.SH SYNOPSIS
.BR #include
.RB < nl_types.h >
.LP
.BR "char *catgets" ( nl_catd
.IR catd ,
.BR int
.IR setnum ,
.BR int
.IR msgnum ,
.BI "const char *" \c
.IR msg )
.
.SH AVAILABILITY
Requires linking with the
.B \-lcatgets
library option.
.
.SH DESCRIPTION
The
.BR catgets ()
function searches in the national language message catalogue
specified by
.IR catd ,
which must have been opened by a preceding call to
.BR catopen (@MAN3EXT@),
for a message in set number
.IR setnum ,
which is identified by the message number
.IR msgnum .
If found,
.BR catgets ()
returns the text of this message;
the
.I msg
argument specifies a default message,
which is returned if the specified message cannot be found
in the catalogue.
.
.SH RETURN VALUE
If the specified message entry is successfully located in
the catalogue,
.BR catgets ()
returns a pointer to the null\-terminated string
defining the text of the message;
if the look\-up is unsuccessful,
.BR catgets ()
returns
.IR msg .
.
.SH ERROR RETURNS
None.
.
.SH CONFORMING TO
POSIX 1003.1-2001.
.
.SH CAVEATS AND BUGS
Text retrieved from a message catalogue is located within
an internal buffer allocated by
.BR catopen (@MAN3EXT@);
it must not be modified by the calling procedure.
.
.LP
The encoding format for message text is defined at the time
the catalogue is compiled by
.BR gencat (@MAN1EXT@).
Nominally,
it may be expected to conform to the
.B LC_MESSAGES
encoding for the active locale,
as established by
.BR setlocale (@MAN3EXT@);
however,
this cannot be easily confirmed by the function calling
.BR catgets ().
Therefore,
the calling procedure should assume that
the returned text matches the locale encoding;
if the message catalogue is known to employ Unicode encoding,
then the calling procedure should process the returned message
as a Unicode string.
.
.SH SEE ALSO
.BR catopen (@MAN3EXT@),
.BR gencat (@MAN1EXT@).
.
.SH AUTHOR
Copyright \(co 2007, Keith Marshall
.
.LP
This man page was written by Keith Marshall
<kei...@us...>
for the MinGW project.
It relates to the MinGW specific implementation of
.BR catgets ().
.
.LP
Permission is granted to copy and redistribute this man page,
either
.IR "as is" ,
or in modified form,
under the terms of the
.IR "GNU Free Documentation License" ,
Version 1.2,
or any later version published by the
.IR "Free Software Foundation, Inc." ,
with no front cover texts,
no back cover texts,
and no invariant sections.
Please refer to
.I http://www.gnu.org/licenses/licenses.html#FDL
for further information.

--- NEW FILE: catclose.man ---
'\"
.TH catclose @MAN3EXT@ 21-Jun-2007 MinGW "MinGW Programming Reference
.
.SH NAME
.B catclose
\- close a national language message catalogue.
.
.\" Copyright (C) 2007,  Keith Marshall.
.
.\" Permission is granted to copy, distribute and/or modify this manpage
.\" under the terms of the GNU Free Documentation License, Version 1.2
.\" or any later version published by the Free Software Foundation, with
.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the accompanying file, `FDL'.
.
.SH SYNOPSIS
.BR #include
.RB < nl_types.h >
.LP
.BR "int catclose" ( nl_catd\c
.IR catd )
.
.SH AVAILABILITY
Requires linking with the
.B \-lcatgets
library option.
.
.SH DESCRIPTION
The
.BR catclose ()
function closes the national language message catlogue,
associated with the descriptor
.I catd
by a preceding call to
.BR catopen (@MAN3EXT@),
and frees all resources allocated to it.
.
.SH RETURN VALUE
On successfully closing
.IR catd ,
.BR catclose ()
returns zero;
on failure it returns
.BR -1 ,
and
.I errno
is set to
.BR EBADF .
.
.SH CONFORMING TO
POSIX 1003.1-2001.
.
.SH CAVEATS AND BUGS
POSIX specifies a further possible error return case,
with
.I errno
set to
.BR EINTR ;
this case should not occur on MS\(hyWindows\*(Tm hosts.
.
.SH SEE ALSO
.BR catopen (@MAN3EXT@).
.
.SH AUTHOR
Copyright \(co 2007, Keith Marshall
.
.LP
This man page was written by Keith Marshall
<kei...@us...>
for the MinGW project.
It relates to the MinGW specific implementation of
.BR catgets (@MAN3EXT@).
.
.LP
Permission is granted to copy and redistribute this man page,
either
.IR "as is" ,
or in modified form,
under the terms of the
.IR "GNU Free Documentation License" ,
Version 1.2,
or any later version published by the
.IR "Free Software Foundation, Inc." ,
with no front cover texts,
no back cover texts,
and no invariant sections.
Please refer to
.I http://www.gnu.org/licenses/licenses.html#FDL
for further information.

--- NEW FILE: catopen.man ---
'\"
.TH catopen @MAN3EXT@ 21-Jun-2007 MinGW "MinGW Programming Reference
.
.SH NAME
.B catopen
\- open a national language message catalogue.
.
.\" Copyright (C) 2007,  Keith Marshall.
.
.\" Permission is granted to copy, distribute and/or modify this manpage
.\" under the terms of the GNU Free Documentation License, Version 1.2
.\" or any later version published by the Free Software Foundation, with
.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the accompanying file, `FDL'.
.
.SH SYNOPSIS
.BR #include
.RB < nl_types.h >
.LP
.BR "nl_catd catopen" ( "const char *" \c
.IR name ,
.BR int
.IR flag )
.
.SH AVAILABILITY
Requires linking with the
.B \-lcatgets
library option.
.
.SH DESCRIPTION
The
.BR catopen ()
function opens a national language message catalogue,
and returns a catalogue descriptor.
Once a message catalogue has been successfully opened,
its descriptor remains valid until explicitly closed by calling
.BR catclose (@MAN3EXT@),
or until the process image is replaced by calling
.BR exec ();
it is
.I never
inherited by any child process invoked by
.BR spawn ()
or by
.BR CreateProcess ().
.
.LP
The
.I name
argument specifies the name of the facility
to which the message catalogue relates.
If it includes a disk drive designator,
any
.BR / " or any " \e
directory/file name separator characters,
then it is assumed to represent an actual path name
for the message catalogue;
otherwise the message catalogue is located by searching
the paths specified by the
.B NLSPATH
environment variable,
substituting
.I name
for the
.B %N
translation specifier.
If no
.B NLSPATH
variable exists in the environment,
or if no message catalogue matching
.I name
is found in any path specified by it,
an internally defined default
.B NLSPATH
is searched.
.
.LP
The
.I flag
argument specifies how
.B NLSPATH
should be interpreted,
when searching for the named message catalogue;
it may be specified as the manifest constant
.BR NL_CAT_LOCALE ,
defined in
.BR nl_types.h ,
or it should be zero.
.
.LP
When searching
.BR NLSPATH ,
either as specified in the environment,
or using the internal default,
the selection of a message catalogue may depend on the
specification for the current locale,
as defined in the environment;
such selection is derived from the definition of
.BR LC_MESSAGES ,
if the
.I flag
argument is given as
.BR NL_CAT_LOCALE ,
or from
.B LANG
otherwise,
and is determined by substitution of the appropriate
components of the respective definition for each of the following
.B NLSPATH
translation specifiers:\(en
.ll -\n(INu
.
.RS
.TP
.B %l
The language specification component
of the locale identification string.
.
.TP
.B %t
The country/territory component
of the locale identification string.
.
.TP
.B %c
The codeset specification component
of the locale identification string.
.
.TP
.B %L
The entire locale identification;
nominally equivalent to
.BR %l_%t.%c .
.RE
.
.ll +\n(INu
.SH RETURN VALUE
If the requested message catalogue is successfully opened,
.BR catopen ()
returns a unique descriptor,
which remains associated with the catalogue for as long
as it remains open.
.
.SH ERROR RETURNS
If the requested catalogue cannot be successfully opened,
.BR catopen ()
returns
.RB ( nl_catd )( -1 ),
(which is
.I never
returned as a valid descriptor),
and
.I errno
is set to one of the following values:\(en
.ll -\n(INu
.
.RS
.TP
.B EACCESS
The user is not permitted to read the message catalogue
associated with the facility specified by
.IR name .
.
.TP
.B EMFILE
The calling process has too many open files.
.
.TP
.B ENOENT
No message catalogue,
associated with the facility specified by
.IR name ,
could be found.
.
.TP
.B ENOMEM
There is insufficient free memory available.
.ll +\n(INu
.RE
.
.SH ENVIRONMENT
.TP
.B NLSPATH
Specifies a list of semicolon separated path names,
by which a message catalogue may be identified.
It may include any,
or all of the following translation specifiers,
in any combination:\(en
.ll -\n(INu
.
.RS
.TP
.B %N
The message catalogue facility name.
.
.TP
.B %l
The language component of the locale specification string.
.
.TP
.B %t
The territory,
or region,
component of the locale specification string.
.
.TP
.B %c
The codeset component of the locale specification string.
.
.TP
.B %L
The fully qualified locale specification string.
.ll +\n(INu
.RE
.
.TP
.B LC_MESSAGES
The locale specification string,
used to establish the
.B NLSPATH
translations for
.BR %l ,
.BR %t ,
.B  %c
and
.BR %L ,
when the
.I flag
argument to
.BR catopen ()
is specified as
.BR NL_CAT_LOCALE .
.
.TP
.B LANG
The locale specification string,
used to establish the
.B NLSPATH
translations for
.BR %l ,
.BR %t ,
.B  %c
and
.BR %L ,
when the
.I flag
argument to
.BR catopen ()
is specified as zero.
.
.SH CONFORMING TO
POSIX 1003.1-2001,
but omitting the reporting of error conditions
which are unsupported by MS\(hyWindows\*(Tm.
.
.SH CAVEATS AND BUGS
When performing an
.B NLSPATH
search,
the strings substituted for the
.BR %l ,
.BR %t ,
.B  %c
and
.B  %L
translation specifiers are copied literally from the
.B  LC_MESSAGES
or
.B  LANG
environment variables,
as appropriate.
If the requisite environment variable is not defined,
then the substitution will be performed on the basis of the
locale identification string for the system
.B LC_CTYPE
category,
(since MS\(hyWindows\*(Tm does not provide native support for the
.B LC_MESSAGES
category),
as returned by
.BR setlocale (@MAN3EXT@);
this will be the long form locale identification string,
which is standard for MS\(hyWindows\*(Tm systems.
If your system uses POSIX conventions for storing message catalogues,
with national language directory names specified as ISO\(hy639 language
or ISO\(hy3166 territory codes,
be sure to set the requisite
.B LC_MESSAGES
or
.B LANG
environment variable accordingly.
.
.SH SEE ALSO
.BR catgets (@MAN3EXT@),
.BR catclose (@MAN3EXT@).
.
.SH AUTHOR
Copyright \(co 2007, Keith Marshall
.
.LP
This man page was written by Keith Marshall
<kei...@us...>
for the MinGW project.
It relates to the MinGW specific implementation of
.BR catgets (@MAN3EXT@).
.
.LP
Permission is granted to copy and redistribute this man page,
either
.IR "as is" ,
or in modified form,
under the terms of the
.IR "GNU Free Documentation License" ,
Version 1.2,
or any later version published by the
.IR "Free Software Foundation, Inc." ,
with no front cover texts,
no back cover texts,
and no invariant sections.
Please refer to
.I http://www.gnu.org/licenses/licenses.html#FDL
for further information.

--- NEW FILE: gencat.man ---
'\"
.TH gencat @MAN3EXT@ 16-Jul-2007 MinGW "MinGW User Commands
.
.SH NAME
.B gencat
\- compile a national language message catalogue for use with
.BR catgets (@MAN3EXT@).
.
.\" Copyright (C) 2007,  Keith Marshall.
.
.\" Permission is granted to copy, distribute and/or modify this manpage
.\" under the terms of the GNU Free Documentation License, Version 1.2
.\" or any later version published by the Free Software Foundation, with
.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the accompanying file, `FDL'.
.
.SH SYNOPSIS
.B gencat
.I catfile
.I msgfile
\&...
.
.SH DESCRIPTION
.B gencat
merges the messages defined in the input file,
or files,
specified by the
.I msgfile
argument list into the binary format national language message catalogue
specified by
.IR catfile .
.
.LP
If
.I catfile
does not exist,
it is created;
if it is specified as
.BR \- ,
or as the special device name
.BR /dev/stdout ,
then the message catalogue is treated as non\(hyexistent,
and it is created by writing the compiled message data to
standard output.
.
.LP
Input files in the
.I msgfile
list are processed in left to right order,
as specified.
If any file name in this
list is specified as
.BR \- ,
or as the special device name
.BR /dev/stdin ,
then standard input is read as the corresponding
.IR msgfile ;
at most one
.I msgfile
should be specified using either of these special
input file names,
in any single invocation of
.BR gencat .
.
.SS Message Catalogue Organisation
Typically,
a collection of message catalogues,
comprising one catalogue for each national language,
will be provided for a single
.IR facility ,
(where a
.I facility
may represent a single application,
or a single logical group of applications).
.
.LP
Within each individual catalogue,
messages are individually numbered,
and organised into numbered
.IR sets ,
such that each message is uniquely identified by
the combination of its set and message numbers;
these are indexed,
to facilitate retrieval of any specific message by the
.BR catgets (@MAN3EXT@)
function.
Within each multilingual collection of message catalogues,
relating to a common
.IR facility ,
each specific combination of set and message numbers refers to
the various national language translations for the same message.
.
.LP
Message text is incorporated into the message catalogues
in the form of NUL terminated strings;
these may be defined using any codeset which may be
appropriate for the respective national language of
each individual message catalogue.
.
.SS Input File Syntax
.B gencat
input files define both the organisation and content
of a message catalogue.
They are
.I text
files,
with individual lines delimited by either
.B LF
or
.B CRLF
line terminators;
every line of input
.I must
be properly terminated,
by either of these line terminators.
.
.LP
Each line of input must represent one of the input record types:\(en
.ll -4n
.
.RS 4n
.TP 4n
.IR "\fB$\fP comment" " ..."
Lines having
.B $
as their first character,
followed by one or more white space characters,
and then any additional characters up to and
including the line terminator,
are considered as comments.
They are parsed in the POSIX locale,
(with conversion of the input encoding from
UTF\(hy16 or UTF\(hy32 if required).
With the execption of the special case of a
.I codeset
declaration,
such comment lines are simply ignored.
.
.TP
.BR "$ codeset" = \fIencoding
This special use of a
.B comment
line is an extension to the POSIX standard.
It functions as a pseudo\(hydirective,
which provides a mechanism for specifying the codeset in which
messages are to be defined,
when this differs from the prevailing codeset
of the language specified for the
.B LC_CTYPE
category of the locale established in the process environment.
This feature is not supported
when the input encoding is implicitly identified as
UTF\(hy16 or UTF\(hy32.
.
.TP
.IR \fB$ < \fBdirective "> " argument " [" comment " ...]"
Lines having
.B $
as their first character,
followed immediately by a directive keyword,
with no intervening white space,
are interpreted as
.B gencat
directives.
The valid directives are:\(en
.ll -4n
.
.RS 4n
.TP 4n
.IR \fB$quote " [<" char ">]"
Identifies a single character,
which is to be interpreted as an optional quoting character,
while parsing subsequent message definitions.
.
.IP
The optional
.RI < char >
argument must represent a single character;
it is interpreted,
possibly as a multi\(hybyte character,
in the input encoding,
which may be implicitly identified as
UTF\(hy16 or UTF\(hy32,
explicitly specified by a
.I codeset
pseudo\(hydirective,
or,
failing either of these,
in the encoding for the
.B LC_CTYPE
category of the locale defined in the
.B gencat
process environment.
This character may be used,
in strict matching pairs,
to surround sections of text within message definitions,
so improving the visibility of trailing white space,
or of empty message definitions,
within the source file;
such pairs of the quote character are
.I not
copied to the message definition in the message catalogue.
.
.IP
If a
.B $quote
directive is issued,
from which the
.RI < char >
argument is omitted,
or if no
.B $quote
directive is specified,
then no quoting character is available
for use in subsequent message definitions.
.
.TP
.IR \fB$set " <" setnum "> [" comment ]
Identifies the set number,
.IR setnum ,
to which subsequently defined messages are to be added,
until the next
.B $set
directive,
or until the end of the source file.
The
.I setnum
argument must represent a decimal integer number in the range from
.B 1
to the value of the manifest constant
.BR NL_SETMAX ,
which is defined in
.IR nl_types.h .
.
.IP
Within any single source file,
set numbers defined by
.B $set
directives must be presented in strictly ascending order,
but they need not be contiguously numbered.
.
.IP
If any source file presents message definitions
before the first of any
.B $set
directives,
or if no
.B $set
directive is present,
then those messages are added to
the set identified by the manifest constant
.BR NL_SETD ,
which is defined in
.IR nl_types.h .
.
.TP
.IR \fB$delset " <" setnum "> [" comment ]
Instructs
.B gencat
to remove all messages,
belonging to the set identified by
.IR setnum ,
from an existing message catalogue.
.RE
.
.TP
.RI < \fBmsgnum "> " "message text" " ... [" \fB\e ]
Lines commencing with a numeric
.B msgnum
tag introduce a new message definition.
The
.B msgnum
tag must be composed of decimal digits from the POSIX portable character set,
converted from UTF\(hy16 or UTF\(hy32 encoding as necessary,
when either of these is used for input,
and must represent a decimal integer number in the range from
.B 1
to the value of the manifest constant
.BR NL_MSGMAX ,
which is defined in
.IR nl_types.h .
It must be separated from the following
.I message text
by exactly one space character;
any additional spaces,
where present,
are significant and are considered to be part of the defined
.IR "message text" .
.
.IP
Within any single message set,
as presented within any single source file,
.B msgnum
records
.I must
be presented in strictly ascending numerical order of
.BR msgnum ;
however,
the message numbers need not be contiguous.
.
.IP
The
.I message text
is interpreted using the encoding of the input stream,
which may be implicitly identified as
UTF\(hy16 or UTF\(hy32,
explicitly specified by a
.I codeset
pseudo\(hydirective,
or,
where neither of these is applicable,
using the encoding for the
.B LC_CTYPE
category of the locale defined in the
.B gencat
process environment.
.
.IP
Within
.IR "message text" ,
the following escape sequences are recognised,
and interpreted in place,
before copying to the message catalogue:\(en
.ll -4n
.
.RS 8n
.TP 9n
.B \eb
backspace.
.
.TP
.B \ef
form feed.
.
.TP
.B \en
newline.
.
.TP
.B \er
carriage return.
.
.TP
.B \et
horizontal tab.
.
.TP
.B \ev
vertical tab.
.
.TP
.B \e\e
a single literal
.B \e
character.
.
.TP
.BR \e < ddd >
octal digit sequence;
the arbitrary length sequence of octal digit characters,
.BR ddd ,
is parsed,
interpreted as the numeric value represented,
and replaced by the single character associated with the corresponding
position in the collating sequence of the input codeset.
.ll +4n
.RE
.
.IP
In addition to the above escape sequences,
if the
.I last
character of
.IR "message text" ,
immediately preceding the
.B LF
or
.B CRLF
line terminator,
is an unescaped
.B \e
character,
or if
.I message text
includes an unpaired instance of the quoting character,
as defined by the
.B $quote
directive,
then the following line is interpreted as a continuation of
.IR "message text" .
.
.IP
When followed by any character,
other than those specified for the above escape sequences,
or the line terminator,
any
.B \e
character appearing in
.I message text
is ignored;
it is not included in the collected
.I message text
which is to be copied to the message catalogue.
.
.IP
If
.B msgnum
is followed by
.I exactly
one white space character,
and immediately thereafter by a
.B LF
or a
.B CRLF
line terminator,
then a zero length message will be entered into the message catalogue.
.
.IP
If
.B msgnum
is immediately followed by a
.B LF
or
.B CRLF
line terminator,
without intervening white space,
then any message in the current message set,
and with the specified message number,
which already exists in the message catalogue,
will be deleted.
.
.TP
.IR "continuation message text" " ... [" \fB\e ]
Any line,
immediately following a message definition record which ends with a
.B \e
escaped
.B LF
or
.B CRLF
terminator,
or which includes an unpaired quoting character,
is parsed as a logical continuation of the message definition;
such continuation may be extended over as many lines as required,
by similarly escaping the line terminator
on each continuation line but the last,
or by deferring the matching of an unpaired quoting character
until the last continuation line.
.
.IP
When a message definition is extended over one or more continuation lines,
the intervening line terminators are not included in the collected
.IR "message text" .
Thus,
each of the following two examples:\(en
.
.nf
.RS
.IP
$quote "
1 Message defined \e
with continuation line.\en
.
.IP
$quote "
1 "Message defined
\ with continuation line.\en"
.RE
.IP
is equivalent to:\(en
.RS
.IP
$quote "
1 Message defined with continuation line.\en
.RE
.fi
.RE
.ll +8n
.
.LP
All
.IR "message text" ,
from each
.B msgnum
definition line and its following continuation lines,
if any,
is interpreted and collected into a single logical message definition.
Each such definition is indexed by
.B setnum
and
.B msgnum
for subsequent retrieval by any application
accessing the message catalogue by calling
.BR catopen (@MAN3EXT@)
and
.BR catgets (@MAN3EXT@),
and is stored in the message catalogue as a NUL terminated string.
.
.SH ENVIRONMENT
The following environment variables may be set,
to control the operation of
.BR gencat :\(en
.ll -4n
.
.TP 4n
.B LC_ALL
If set
.B LC_ALL
defines the language,
territory and encoding attributes to be associated with the
.B LC_CTYPE
and
.B LC_MESSAGE
locale categories.
.
.TP
.B LC_CTYPE
If
.B LC_ALL
is not defined,
the encoding attribute from the locale category defined by
.B LC_CTYPE
is used to establish the default codeset for the message catalogue,
when the input encoding cannot be identified as either UTF\(hy16 or UTF\(hy32,
and there is no
.B codeset
pseudo\(hydirective specified in the input stream.
.
.TP
.B LC_MESSAGES
If
.B LC_ALL
is not defined,
.B LC_MESSAGES
defines the language,
territory and encoding attributes identifying a message catalogue,
in which
.BR gencat \(aqs
own diagnostic messages are defined.
.
.TP
.B NLSPATH
Defines the search path used to locate message catalogues,
in which
.BR gencat \(aqs
own diagnostic messages are defined.
.B NLSPATH
should be a semicolon separated list of directory paths,
in the format required by
.BR catopen (@MAN3EXT@).
.
.SH CONFORMING TO
POSIX 1003.1-2001.
.
.SH CAVEATS AND BUGS
Neither the automatic detection of UTF\(hy16 or UTF\(hy32
input encoding formats,
nor the use of the
.B codeset
pseudo\(hydirective to specify message catalogue encoding,
is mandated by POSIX.
While some other
.B gencat
implementations are known to support the
.B codeset
pseudo\(hydirective,
neither of these features is guaranteed to be portable.
.
.LP
Similarly,
the use of unpaired quoting characters to extend message definitions,
over one or more continuation lines,
is an extension to POSIX requirements,
and may not be portable to other
.B gencat
implementations.
.
.LP
POSIX requires that no individual message shall be greater in length
than the value of the manifest constant
.BR NL_TEXTMAX ,
which is defined in
.IR nl_types.h ;
this implementation does not enforce this limitation.
.
.LP
POSIX stipulates that the manifest constants
.BR NL_SETMAX ,
.B  NL_MSGMAX
and
.BR NL_TEXTMAX ,
should be defined in
.IR limits.h ;
this implementation defines them in
.I nl_types.h
instead.
.
.SH SEE ALSO
.BR catopen (@MAN3EXT@),
.BR catgets (@MAN3EXT@),
.BR catclose (@MAN3EXT@).
.
.SH AUTHOR
Copyright \(co 2007, Keith Marshall
.
.LP
This man page was written by Keith Marshall
<kei...@us...>
for the MinGW project.
It relates to the MinGW specific implementation of
.BR catgets (@MAN3EXT@).
.
.LP
Permission is granted to copy and redistribute this man page,
either
.IR "as is" ,
or in modified form,
under the terms of the
.IR "GNU Free Documentation License" ,
Version 1.2,
or any later version published by the
.IR "Free Software Foundation, Inc." ,
with no front cover texts,
no back cover texts,
and no invariant sections.
Please refer to
.I http://www.gnu.org/licenses/licenses.html#FDL
for further information.

Update of /cvsroot/mingw/catgets/man
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv12639/man

Log Message:
Directory /cvsroot/mingw/catgets/man added to the repository

Update of /cvsroot/mingw/catgets
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv14214

Modified Files:
	ChangeLog Makefile.in catclose.c 
Log Message:
* catclose.c (mc_close): Error out, if descriptor for message catalogue to be closed lies outside the valid range.


Index: Makefile.in
===================================================================
RCS file: /cvsroot/mingw/catgets/Makefile.in,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** Makefile.in	18 Jun 2007 22:36:06 -0000	1.2
--- Makefile.in	16 Jul 2007 19:59:42 -0000	1.3
***************
*** 7,14 ****
  # $Id$
  #
! # Copyright (C) 2006, Keith Marshall
  #
  # Written by Keith Marshall  <kei...@us...>
! # Last modification: 30-Dec-2006
  #
  #
--- 7,14 ----
  # $Id$
  #
! # Copyright (C) 2006, 2007, Keith Marshall
  #
  # Written by Keith Marshall  <kei...@us...>
! # Last modification: 20-Jun-2007
  #
  #
***************
*** 28,32 ****
  
  srcdir = @srcdir@
! VPATH = ${srcdir}:${srcdir}/include:${srcdir}/repl
  
  prefix = @prefix@
--- 28,32 ----
  
  srcdir = @srcdir@
! VPATH = ${srcdir}:${srcdir}/include:${srcdir}/repl:${srcdir}/man
  
  prefix = @prefix@
***************
*** 95,98 ****
--- 95,128 ----
  MISC_SOURCES	= $(CONFIG_HEADERS) $(CONFIG_SOURCES) $(INSTALL_PROGS)
  
+ MANPAGE_SOURCES	= catopen.man catgets.man catclose.man gencat.man
+ 
+ # MANSECTS specifies the set of *standard* man section identifiers, to
+ # which this collection of man pages will be distributed, or to which
+ # references are made in any man page in the collection.
+ #
+ MANSECTS = 1 2 3
+ 
+ # The set of MAN<n>EXT macros allows us to define local aliases for each
+ # of the standard man section identifiers; these will be used instead of
+ # the standard identifiers, as extensions for the installed man page
+ # directories and file names.
+ #
+ MAN1EXT = 1
+ MAN2EXT = 2
+ MAN3EXT = 3
+ 
+ # The following set of macros facilitate identification of the man
+ # section to which each generated `page.n' file belongs; this requires
+ # the `TH' record in each corresponding `page.man' source file to
+ # identify the appropriate section with a `@MAN<n>EXT@' tag.
+ #
+ mansect_lookup = '/^\.TH/{s/.*\(@MAN[0-9][^@]*EXT@\).*/\1/'
+ mansect_transform = $(foreach s,$(MANSECTS),-e s/@MAN$sEXT@/$(MAN$sEXT)/g)
+ mansect = -e $(mansect_lookup) $(mansect_transform) -e q -e \} -e d
+ manpage = ${mandir}/man$$section/$$pagename.$$section
+ 
+ # Generic rule to create `page.n' from `page.man'...
+ #
+ %.n: %.man; sed $(mansect_transform) $< > $@
  
  BUILD_PROGS	= gencat$(EXEEXT)
***************
*** 103,115 ****
  INSTALL_PROGS	= gendefs.awk
  
  %.$(OBJEXT): %.c
  	$(CC) -c $(CFLAGS) $(INCLUDES) $(DEFS) $(LDFLAGS) $<
  
  %.h: %.h.in Makefile
  	sed $(HEADER_TRANSFORM_SCRIPT) $< > $@
  
- %.h: repl/include/%.h
- 	$(LN_S) $< $@
- 
  HEADER_TRANSFORM_SCRIPT = \
    -e 's,@HOST_PREFIX@,${canonical_prefix},g' \
--- 133,147 ----
  INSTALL_PROGS	= gendefs.awk
  
+ # Generic rule, replacing the built-in default, to create an object file
+ # from a C source file...
+ #
  %.$(OBJEXT): %.c
  	$(CC) -c $(CFLAGS) $(INCLUDES) $(DEFS) $(LDFLAGS) $<
  
+ # Generic rule to create a local header from a template...
+ #
  %.h: %.h.in Makefile
  	sed $(HEADER_TRANSFORM_SCRIPT) $< > $@
  
  HEADER_TRANSFORM_SCRIPT = \
    -e 's,@HOST_PREFIX@,${canonical_prefix},g' \
***************
*** 119,125 ****
  AUTOGENERATED = Automatically generated from $<; do not edit!
  
  all-dll = @MAKE_DLL@
  
! all: all-libs $(all-dll) all-bin
  
  all-bin: $(BUILD_PROGS)
--- 151,162 ----
  AUTOGENERATED = Automatically generated from $<; do not edit!
  
+ # Generic rule to make a replacement header available for use...
+ #
+ %.h: repl/include/%.h
+ 	$(LN_S) $< $@
+ 
  all-dll = @MAKE_DLL@
  
! all: all-libs $(all-dll) all-bin all-doc
  
  all-bin: $(BUILD_PROGS)
***************
*** 129,132 ****
--- 166,178 ----
  all-libs: $(BUILD_LIBS)
  
+ all-doc: all-man all-info all-htmldoc all-pdf all-ps
+ 
+ all-man: $(subst .man,.n,$(MANPAGE_SOURCES))
+ 
+ all-info:
+ all-htmldoc:
+ all-pdf:
+ all-ps:
+ 
  gencat$(EXEEXT): $(GENCAT_OBJECTS)
  	$(CC) -o $@ $(CFLAGS) $(LDFLAGS) $^ $(LIBICONV) $(LIBS)
***************
*** 185,189 ****
  install-doc: install-man install-info install-htmldoc install-pdf install-ps
  
! install-man:
  install-info:
  install-htmldoc:
--- 231,241 ----
  install-doc: install-man install-info install-htmldoc install-pdf install-ps
  
! install-man: $(subst .man,.n,$(MANPAGE_SOURCES))
! 	for file in $^; do \
! 	  pagename=`echo $$file | sed 's/\.n//'`; \
! 	  section=`sed $(mansect) ${srcdir}/$$pagename.man`; \
! 	  echo $(INSTALL_DATA) $$file $(manpage); \
! 	done
! 
  install-info:
  install-htmldoc:
***************
*** 199,203 ****
  dist_srcdir = @abs_top_srcdir@
  
! DISTDIRS = include m4 repl repl/include
  DISTFILES = $(GENCAT_SOURCES) $(CATGETS_SOURCES) $(OTHER_SOURCES)
  DISTNAME = $(PACKAGE)-$(VERSION)
--- 251,255 ----
  dist_srcdir = @abs_top_srcdir@
  
! DISTDIRS = include m4 repl repl/include man
  DISTFILES = $(GENCAT_SOURCES) $(CATGETS_SOURCES) $(OTHER_SOURCES)
  DISTNAME = $(PACKAGE)-$(VERSION)
***************
*** 234,238 ****
  clean:
  	rm -f nlspath.h $(LOCAL_HEADERS) $(REPLACEMENT_HEADERS)
! 	rm -f *.$(OBJEXT) *~ gencat$(EXEEXT)
  
  distclean: clean
--- 286,290 ----
  clean:
  	rm -f nlspath.h $(LOCAL_HEADERS) $(REPLACEMENT_HEADERS)
! 	rm -f *.$(OBJEXT) *~ gencat$(EXEEXT) *.n *.a *.dll
  
  distclean: clean

Index: catclose.c
===================================================================
RCS file: /cvsroot/mingw/catgets/catclose.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** catclose.c	6 Apr 2007 22:34:52 -0000	1.1.1.1
--- catclose.c	16 Jul 2007 19:59:42 -0000	1.2
***************
*** 31,34 ****
--- 31,35 ----
  #include <stdarg.h>
  #include <mctab.h>
+ #include <errno.h>
  
  static
***************
*** 36,41 ****
  {
    /* This call-back function provides the actual `catclose' implementation.
     */
!   return (void *)_mc_free_( cdt->tab + va_arg( argv, int ) );
  }
  
--- 37,61 ----
  {
    /* This call-back function provides the actual `catclose' implementation.
+    * There is one entry in the `argv' vector, representing the descriptor
+    * for the catalogue which is to be closed.
     */
!   int catd = va_arg( argv, int );
!   if( (catd < 0) || (catd >= cdt->curr_size) )
!   {
!     /* The catalogue descriptor is simply an integer index into an array
!      * of pointers to the actual message catalogue data structures.  There
!      * are exactly cdt->curr_size elements in this descriptor array, with
!      * index values ranging from 0 .. cdt->curr_size - 1; if here, then
!      * the value of catd falls outside this range, we decline to accept
!      * it, bailing out with errno = EBADF, as specified by POSIX.
!      */
!     errno = EBADF;
!     return (void *)(-1);
!   }
!   /* If we get past this validity check, then we simply hand off the task
!    * of closing the message catalogue, and freeing its resource allocation,
!    * to the _mc_free_ function.
!    */
!   return (void *)_mc_free_( cdt->tab + catd );
  }
  

Index: ChangeLog
===================================================================
RCS file: /cvsroot/mingw/catgets/ChangeLog,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** ChangeLog	18 Jun 2007 22:36:06 -0000	1.14
--- ChangeLog	16 Jul 2007 19:59:42 -0000	1.15
***************
*** 1,2 ****
--- 1,7 ----
+ 2007-07-16  Keith Marshall  <kei...@us...>
+ 
+ 	* catclose.c (mc_close): Error out, if descriptor for message
+ 	catalogue to be closed lies outside the valid range.
+ 
  2007-06-18  Keith Marshall  <kei...@us...>