catgets(3int)

Name

catgets − read a program message

Syntax

#include <nl_types.h>

char *catgets (catd, set_num, msg_num, s)
nl_catd catd;
int set_num, msg_num;
char *s;

Description

The function catgets attempts to read message msg_num in set set_num from the message catalog identified by catd. The parameter catd is a catalog descriptor returned from an earlier call to catopen. The pointer, s, points to a default message string. The catgets function returns the default message if the identified message catalog is not currently available.

The catgets function stores the message text it returns in an internal buffer area. This buffer area might be written over by a subsequent call to catgets. If you want to re-use or modify the message text, you should copy it to another location.

The arguments set_num and msg_num are defined as integer values to make programs that contain the catgets call portable. Where possible, you should use symbolic names for message and set numbers, instead of hard-coding integer values into your source programs. If you use symbolic names, you must include the header file that gencat &−h creates in all your program modules.

Examples

The following example shows using the catgets call to retrieve a message from a message catalog that uses symbolic names for set and message numbers:

nl_catd catd = catopen (messages.msf, 0)
message = catgets (catd, error_set, bad_value, "Invalid value")

When this call executes, catgets searches for the message catalog identified by the catalog descriptor stored in catd. The function searches for the message identified by the bad_value symbolic name in the set identified by the error_set symbolic name and stores the message text in message. If catgets cannot find the message, it returns the message Invalid value.

Return Values

If catgets successfully retrieves the message, it returns a pointer to an internal buffer area containing the null terminated message string. If the call is unsuccessful for any reason, catgets returns the default message in s.

Museum