The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2003 Edition
Copyright © 2001-2003 The IEEE and The Open Group, All Rights reserved.

NAME

catgets - read a program message

SYNOPSIS

[XSI] [Option Start] #include <nl_types.h>

char *catgets(nl_catd
catd, int set_id, int msg_id, const char *s); [Option End]

DESCRIPTION

The catgets() function shall attempt to read message msg_id, in set set_id, from the message catalog identified by catd. The catd argument is a message catalog descriptor returned from an earlier call to catopen(). The s argument points to a default message string which shall be returned by catgets() if it cannot retrieve the identified message.

The catgets() function need not be reentrant. A function that is not required to be reentrant is not required to be thread-safe.

RETURN VALUE

If the identified message is retrieved successfully, catgets() shall return a pointer to an internal buffer area containing the null-terminated message string. If the call is unsuccessful for any reason, s shall be returned and errno may be set to indicate the error.

ERRORS

The catgets() function may fail if:

[EBADF]
The catd argument is not a valid message catalog descriptor open for reading.
[EBADMSG]
The message identified by set_id and msg_id in the specified message catalog did not satisfy implementation-defined security criteria.
[EINTR]
The read operation was terminated due to the receipt of a signal, and no data was transferred.
[EINVAL]
The message catalog identified by catd is corrupted.
[ENOMSG]
The message identified by set_id and msg_id is not in the message catalog.

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

catclose() , catopen() , the Base Definitions volume of IEEE Std 1003.1-2001, <nl_types.h>

CHANGE HISTORY

First released in Issue 2.

Issue 5

A note indicating that this function need not be reentrant is added to the DESCRIPTION.

Issue 6

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety.

End of informative text.


UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]