Technical Reference: Kernel and Subsystems, Volume 1

NLuprintf Kernel Service

Purpose

Submits a request to print an internationalized message to a process' controlling terminal.

Syntax

#include <sys/uprintf.h>

int NLuprintf (Uprintf)
struct uprintf *Uprintf;

Parameters

Uprintf

Points to a uprintf request structure.

Description

The NLuprintf kernel service submits a internationalized kernel message request with the uprintf request structure specified by the Uprintf parameter as input. Once the request has been successfully submitted, the uprintfd daemon retrieves, converts, formats, and writes the message described by the uprintf request structure to a process' controlling terminal.

The caller must initialize the uprintf request structure before calling the NLuprintf kernel service. Fields in the uprintf request structure use several constants. The following constants are defined in the /usr/include/sys/uprintf.h file:

UP_MAXSTR
UP_MAXARGS
UP_MAXCAT
UP_MAXMSG

The uprintf request structure consists of the following fields:

Field	Description
`Uprintf->upf_defmsg`	Points to a default message format. The default message format is a character string that contains either or both of two types of objects: Plain characters, which are copied to the message output stream Conversion specifications, each of which causes zero or more items to be fetched from the Uprintf->arg value parameter array Each conversion specification consists of a % (percent sign) followed by a character that indicates the type of conversion to be applied: % Performs no conversion. Prints a % character. d, i Accepts an integer value and converts it to signed decimal notation. u Accepts an integer value and converts it to unsigned decimal notation. o Accepts an integer value and converts it to unsigned octal notation. x Accepts an integer value and converts it to unsigned hexadecimal notation. c Accepts and prints a char value. s Accepts a value as a string (character pointer). Characters from the string are printed until a \0 (null character) is encountered. Field-width or precision conversion specifications are not supported. The maximum length of the default message-format string pointed to by the `Uprintf->upf_defmsg` field is the number of characters specified by the UP_MAXSTR constant. The `Uprintf->upf_defmsg` field must be a nonnull character. The default message format is used in constructing the kernel message if the message format described by the `Uprintf->upf_NLsetno` and `Uprint->upf_NLmsgno` fields cannot be retrieved from the message catalog specified by `Uprintf->upf_NLcatname`. The conversion specifications contained within the default message format should match those contained in the message format specified by the `upf_NLsetno` and `upf_NLmsgno` fields.
`Uprintf->upf_arg[UP_MAXARGS]`	Specifies from zero to the number of value parameters specified by the UP_MAXARGS constant. A Value parameter may be a integer value, a character value, or a string value (character pointer). Strings are limited in length to the number of characters specified by the UP_MAXSTR constant. String value parameters must be nonnull characters. The number, type, and order of items in the Value parameter array should match the conversion specifications within the message format string.
`Uprintf->upf_NLcatname`	Points to the message catalog file name. If the catalog file name referred to by the `Uprintf->upf_NLcatname` field begins with a / (slash), it is assumed to be an absolute path name. If the catalog file name is not an absolute path name, the process environment determines the directory paths to search. The maximum length of the catalog file name is limited to the number of characters specified by the UP_MAXCAT constant. The value of the `Uprintf->upf_NLcatname` field must be a nonnull character.
`Uprintf->upf_NLsetno`	Specifies the set ID.
`Uprintf->upf_NLmsgno`	Specifies the message ID. The `Uprintf->upf_NLsetno` and `Uprintf->upf_NLmsgno` fields specify a particular message format string to be retrieved from the message catalog specified by the `Uprintf->upf_NLcatname` field. The maximum length of the constructed kernel message is limited to the number of characters specified by the UP_MAXMSG constant. Messages larger then the number of characters specified by the UP_MAXMSG constant are discarded.

Execution Environment

The NLuprintf kernel service can be called from the process environment only.

Return Values

0	Indicates a successful operation.
ENOMEM	Indicates that memory is not available to buffer the request.
ENODEV	Indicates that a controlling terminal does not exist for the process.
ESRCH	Indicates the uprintfd daemon is not active. No requests may be submitted.
EINVAL	Indicates that the message catalog file-name pointer is null or the catalog file name is greater than the number of characters specified by the UP_MAXCAT constant.
EINVAL	Indicates that a string-value parameter pointer is null or the string-value parameter is greater than the number of characters specified by the UP_MAXCAT constant.
EINVAL	Indicates one of the following: Default message format pointer is null. Number of characters in the default message format is greater than the number specified by the UP_MAXSTR constant. Number of conversion specifications contained within the default message format is greater than the number specified by the UP_MAXARGS constant.

Related Information

The uprintf kernel service.

The uprintfd daemon.

Process and Exception Management Kernel Services in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.