The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> catgets - read a program message

#### SYNOPSIS

> ``#include <nl_types.h>
> char *catgets(nl_catd` catd`, int` set_id`, int` msg_id`, const char *`s`);
> ``

#### 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 results are undefined if catd is not a value returned by catopen() for a message catalog still open in the process. 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 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 shall be set to indicate the error.

#### ERRORS

> The catgets() function shall fail if:

> [EINTR]
>   The read operation was terminated due to the receipt of a signal, and no data was transferred.
> [ENOMSG]
>   The message identified by set_id and msg_id is not in the message catalog.

> 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.
> [EINVAL]
>   The message catalog identified by catd is corrupted.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> catclose, catopen

> XBD <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.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #044 is applied, changing the ``may fail'' [EINTR] and [ENOMSG] errors to become ``shall fail'' errors, updating the RETURN VALUE section, and updating the DESCRIPTION to note that: ``The results are undefined if catd is not a value returned by catopen() for a message catalog still open in the process.

> Austin Group Interpretation 1003.1-2001 #148 is applied, adding

> The catgets() function is moved from the XSI option to the Base.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]