man3/catgets.3

   1 '\" t
   2 .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Updated, aeb, 980809
   7 .TH catgets 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 catgets \- get message from a message catalog
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <nl_types.h>
  16 .P
  17 .BI "char *catgets(nl_catd " catalog ", int " set_number \
  18 ", int " message_number ,
  19 .BI "              const char *" message );
  20 .fi
  21 .SH DESCRIPTION
  22 .BR catgets ()
  23 reads the message
  24 .IR message_number ,
  25 in set
  26 .IR set_number ,
  27 from the message catalog identified by
  28 .IR catalog ,
  29 where
  30 .I catalog
  31 is a catalog descriptor returned from an earlier call to
  32 .BR catopen (3).
  33 The fourth argument,
  34 .IR message ,
  35 points to a default message string which will be returned by
  36 .BR catgets ()
  37 if the identified message catalog is not currently available.
  38 The
  39 message-text is contained in an internal buffer area and should be copied by
  40 the application if it is to be saved or modified.
  41 The return string is
  42 always terminated with a null byte (\[aq]\e0\[aq]).
  43 .SH RETURN VALUE
  44 On success,
  45 .BR catgets ()
  46 returns a pointer to an internal buffer area
  47 containing the null-terminated message string.
  48 On failure,
  49 .BR catgets ()
  50 returns the value
  51 .IR message .
  52 .SH ATTRIBUTES
  53 For an explanation of the terms used in this section, see
  54 .BR attributes (7).
  55 .TS
  56 allbox;
  57 lbx lb lb
  58 l l l.
  59 Interface       Attribute       Value
  60 T{
  61 .na
  62 .nh
  63 .BR catgets ()
  64 T}      Thread safety   MT-Safe
  65 .TE
  66 .SH STANDARDS
  67 POSIX.1-2008.
  68 .SH HISTORY
  69 POSIX.1-2001.
  70 .P
  71 The
  72 .BR catgets ()
  73 function is available only in libc.so.4.4.4c and above.
  74 .P
  75 The Jan 1987 X/Open Portability Guide specifies a more subtle
  76 error return:
  77 .I message
  78 is returned if the message catalog specified by
  79 .I catalog
  80 is not available, while an empty string is returned
  81 when the message catalog is available but does not contain
  82 the specified message.
  83 These two possible error returns seem to be discarded in SUSv2
  84 in favor of always returning
  85 .IR message .
  86 .SH SEE ALSO
  87 .BR catopen (3),
  88 .BR setlocale (3)