gettxt(3c) - osol9

1gettxt(3C)               Standard C Library Functions               gettxt(3C)
2
3
4

NAME

6       gettxt - retrieve a text string
7

SYNOPSIS

9       #include <nl_types.h>
10
11       char *gettxt(const char *msgid, const char *dflt_str);
12
13

DESCRIPTION

15       The  gettxt() function retrieves a text string from a message file. The
16       arguments to the function are a  message  identification  msgid  and  a
17       default string dflt_str to be used if the retrieval fails.
18
19
20       The  text  strings  are  in  files  created  by the mkmsgs utility (see
21       mkmsgs(1))      and       installed       in       directories       in
22       /usr/lib/locale/locale/LC_MESSAGES.
23
24
25       The  directory  locale  can be viewed as the language in which the text
26       strings are written. The user can request that messages be displayed in
27       a specific language by setting the environment variable LC_MESSAGES. If
28       LC_MESSAGES is not set, the environment variable LANG will be used.  If
29       LANG   is   not   set,   the   files  containing  the  strings  are  in
30       /usr/lib/locale/C/LC_MESSAGES/*.
31
32
33       The user can also change the language in which the  messages  are  dis‐
34       played  by  invoking  the  setlocale(3C)  function with the appropriate
35       arguments.
36
37
38       If gettxt() fails to retrieve a message in a specific language it  will
39       try  to retrieve the same message in U.S. English. On failure, the pro‐
40       cessing depends on what the  second  argument  dflt_str  points  to.  A
41       pointer  to  the  second argument is returned if the second argument is
42       not the null string. If  dflt_str points to the null string, a  pointer
43       to the U.S. English text string "Message not found!!\n" is returned.
44
45
46       The following depicts the acceptable syntax of msgid for a call to get‐
47       txt().
48
49
50       <msgid> = <msgfilename>:<msgnumber>
51
52
53       The first field is used to indicate the file  that  contains  the  text
54       strings  and must be limited to 14 characters. These characters must be
55       selected from the set of all character values excluding \0  (null)  and
56       the  ASCII code for / (slash) and : (colon). The names of message files
57       must be the same as the names of files created by mkmsgs and  installed
58       in  /usr/lib/locale/locale/LC_MESSAGES/*.  The  numeric field indicates
59       the sequence number of the string in the file. The strings are numbered
60       from 1 to n where n is the number of strings in the file.
61

RETURN VALUES

63       Upon failure to pass either the correct msgid or a valid message number
64       to  gettxt(), a pointer to the text string "Message not  found!!\n"  is
65       returned.
66

USAGE

68       It is recommended that gettext(3C) be used in place of this function.
69

EXAMPLES

71       Example 1 Example of gettxt() function.
72
73
74       In the following example,
75
76
77         gettxt("UX:10", "hello world\n")
78         gettxt("UX:10", "")
79
80
81
82       UX  is  the  name  of the file that contains the messages and 10 is the
83       message number.
84
85

FILES

87       /usr/lib/locale/C/LC_MESSAGES/*
88
89           contains  default message files created by mkmsgs
90
91
92       /usr/lib/locale/locale/LC_MESSAGES/*
93
94           contains message files for different languages created by mkmsgs
95
96

ATTRIBUTES

98       See attributes(5) for descriptions of the following attributes:
99
100
101
102
103       ┌─────────────────────────────┬─────────────────────────────┐
104       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
105       ├─────────────────────────────┼─────────────────────────────┤
106       │MT-Level                     │Safe with exceptions         │
107       └─────────────────────────────┴─────────────────────────────┘
108