lib/libc/nls/catgets.3

   1 .\"     $NetBSD: catgets.3,v 1.15 2003/04/16 13:34:42 wiz Exp $
   2 .\"
   3 .\" Written by J.T. Conklin <jtc@NetBSD.org>.
   4 .\" Public domain.
   5 .\"
   6 .Dd February 12, 2003
   7 .Dt CATGETS 3
   8 .Os
   9 .Sh NAME
  10 .Nm catgets
  11 .Nd retrieve string from message catalog
  12 .Sh LIBRARY
  13 .Lb libc
  14 .Sh SYNOPSIS
  15 .In nl_types.h
  16 .Ft char *
  17 .Fn catgets "nl_catd catd" "int set_id" "int msg_id" "const char *s"
  18 .Sh DESCRIPTION
  19 The
  20 .Fn catgets
  21 function attempts to retrieve message
  22 .Fa msg_id
  23 of set
  24 .Fa set_id
  25 from the message catalog referenced by the descriptor
  26 .Fa catd .
  27 The argument
  28 .Fa s
  29 points to a default message which is returned if the function
  30 is unable to retrieve the specified message.
  31 .Sh RETURN VALUES
  32 If the specified message was retrieved successfully,
  33 .Fn catgets
  34 returns a pointer to an internal buffer containing the message string;
  35 otherwise it returns
  36 .Fa s .
  37 .Sh ERRORS
  38 The
  39 .Fn catgets
  40 function will fail if:
  41 .Bl -tag -width Er
  42 .It Bq Er EBADF
  43 The
  44 .Fa catd
  45 argument is not a valid message catalog descriptor open for reading.
  46 .It Bq Er EINTR
  47 The operation was interrupted by a signal.
  48 .It Bq Er ENOMSG
  49 The message identified by
  50 .Fa set_id
  51 and
  52 .Fa msg_id
  53 is not in the message catalog.
  54 .El
  55 .Sh SEE ALSO
  56 .Xr gencat 1 ,
  57 .Xr catclose 3 ,
  58 .Xr catopen 3 ,
  59 .Xr nls 7
  60 .Sh STANDARDS
  61 The
  62 .Fn catgets
  63 function conforms to
  64 .St -xpg4.2 .
  65 .Pp
  66 Major Unix vendors are split over the adoption of the two most
  67 important message catalog specifications: catgets or
  68 .Xr gettext 3 .
  69 The primary concern with the catgets interface is that every
  70 translatable string has to define a number (or a symbolic constant)
  71 which must correspond to the message in the catalog.
  72 Duplicate message IDs are not allowed.
  73 Constructing message catalogs is difficult.