[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Kernel and Subsystems Technical Reference, 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:

The uprintf request structure consists of the following fields:

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.

Implementation Specifics

This NLuprintf kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The uprintf kernel service.

The uprintfd daemon.

Process and Exception Management Kernel Services in AIX Kernel Extensions and Device Support Programming Concepts.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]