Document revision date: 15 July 2002

The nl and nonl functions are provided only for UNIX software compatibility and have no function in the OpenVMS environment.

Format

#include <curses.h>

void nl (void);

void nonl (void);

Returns a pointer to a string that contains information obtained from the program's current locale.

Format

#include <langinfo.h>

char *nl_langinfo (nl_item item);

Argument

item

The name of a constant that specifies the information required. These constants are defined in <langinfo.h> .

The following constants are valid:

Constant	Category	Description
D_T_FMT	LC_TIME	String for formatting date and time
D_FMT	LC_TIME	String for formatting date
T_FMT	LC_TIME	String for formatting time
T_FMT_AMPM	LC_TIME	Time format with AM/PM string
AM_STR	LC_TIME	String that represents AM in 12-hour clock notation
PM_STR	LC_TIME	String that represents PM in 12-hour clock notation
DAY_1	LC_TIME	The name of the first day of the week
...
DAY_7	LC_TIME	The name of the seventh day of the week
ABDAY_1	LC_TIME	The abbreviated name of the first day of the week
...
ABDAY_7	LC_TIME	The abbreviated name of the seventh day of the week
MON_1	LC_TIME	The name of the first month in the year
...
MON_12	LC_TIME	The name of the twelfth month in the year
ABMON_1	LC_TIME	The abbreviated name of the first month in the year
...
ABMON_12	LC_TIME	The abbreviated name of the twelfth month in the year
ERA	LC_TIME	Era description strings
ERA_D_FMT	LC_TIME	Era date format string
ERA_T_FMT	LC_TIME	Era time format
ERA_D_T_FMT	LC_TIME	Era date and time format
ALT_DIGITS	LC_TIME	Alternative symbols for digits
RADIXCHAR	LC_NUMERIC	The radix character
THOUSEP	LC_NUMERIC	The character used to separate groups of digits in nonmonetary values
YESEXP	LC_MESSAGES	The expression for affirmative responses to yes/no questions
NOEXP	LC_MESSAGES	The expression for negative responses to yes/no questions
CRNCYSTR	LC_MONETARY	The currency symbol. It is preceded by one of the following: A minus ( - ) if the symbol is to appear before the value A plus (+) if the symbol is to appear after the value A period (.) if the symbol replaces the radix character
CODESET	LC_CTYPE	Codeset name

Description

If the current locale does not have language information defined, the function returns information from the C locale. The program should not modify the string returned by the function. This string might be overwritten by subsequent calls to nl_langinfo .

If the setlocale function is called after a call to nl_langinfo , then the pointer returned by the previous call to nl_langinfo will be unspecified. In this case, the nl_langinfo function should be called again.

Return Value

x	Pointer to the string containing the requested information. If item is invalid, the function returns an empty string.

Example

#include <stdio.h> #include <locale.h> #include <langinfo.h> /* This test sets up the British English locale, and then */ /* inquires on the data and time format, first day of the week, */ /* and abbreviated first day of the week. */ #include <stdlib.h> #include <string.h> int main() { char *return_val; char *nl_ptr; /* set the locale, with user supplied locale name */ return_val = setlocale(LC_ALL, "en_gb.iso8859-1"); if (return_val == NULL) { printf("ERROR : The locale is unknown"); exit(1); } printf("+----------------------------------------+\n"); /* Get the date and time format from the locale. */ printf("D_T_FMT = "); /* Compare the returned string from nl_langinfo with */ /* an empty string. */ if (!strcmp((nl_ptr = (char *) nl_langinfo(D_T_FMT)), "")) { /* The string returned was empty this could mean that either */ /* 1) The locale does not contain a value for this item */ /* 2) The value for this item is an empty string */ printf("nl_langinfo returned an empty string\n"); } else { /* Display the date and time format */ printf("%s\n", nl_ptr); } /* Get the full name for the first day of the week from locale */ printf("DAY_1 = "); /* Compare the returned string from nl_langinfo with */ /* an empty string. */ if (!strcmp((nl_ptr = (char *) nl_langinfo(DAY_1)), "")) { /* The string returned was empty this could mean that either */ /* 1) The locale does not contain a value for the first */ /* day of the week */ /* 2) The value for the first day of the week is */ /* an empty string */ printf("nl_langinfo returned an empty string\n"); } else { /* Display the full name of the first day of the week */ printf("%s\n", nl_ptr); } /* Get the abbreviated name for the first day of the week from locale */ printf("ABDAY_1 = "); /* Compare the returned string from nl_langinfo with an empty */ /* string. */ if (!strcmp((nl_ptr = (char *) nl_langinfo(ABDAY_1)), "")) { /* The string returned was empty this could mean that either */ /* 1) The locale does not contain a value for the first */ /* day of the week */ /* 2) The value for the first day of the week is an */ /* empty string */ printf("nl_langinfo returned an empty string\n"); } else { /* Display the abbreviated name of the first day of the week */ printf("%s\n", nl_ptr); } }

Running the example program produces the following result:

+----------------------------------------+ D_T_FMT = %a %e %b %H:%M:%S %Y DAY_1 = Sunday ABDAY_1 = Sun

Generates uniformly distributed pseudorandom-number sequences. Returns 48-bit signed long integers.

Format

#include <stdlib.h>

long int nrand48 (unsigned short int xsubi[3]);

Arguments

xsubi

An array of three short int that, when concatentated together, form a 48-bit integer.

Description

The nrand48 function generates pseudorandom numbers using the linear congruential algorithm and 48-bit integer arithmetic.

The nrand48 function returns nonnegative, long integers uniformly distributed over the range of y values, such that 0 <= y < 2³¹ .

The function works by generating a sequence of 48-bit integer values, Xi, according to the linear congruential formula:

Xn+1 = (aXn+c)mod m n >= 0

The argument m equals 2⁴⁸ , so 48-bit integer arithmetic is performed. Unless you invoke the lcong48 function, the multiplier value a and the addend value c are:

a = 5DEECE66D16 = 2736731631558 c = B16 = 138

The nrand48 function requires that the calling program pass an array as the xsubi argument, which for the first call must be initialized to the initial value of the pseudorandom-number sequence. Unlike the drand48 function, it is not necessary to call an initialization function prior to the first call.

By using different arguments, the nrand48 function allows separate modules of a large program to generate several independent sequences of pseudorandom numbers. For example, the sequence of numbers that one module generates does not depend upon how many times the functions are called by other modules.

Return Value

n	Returns nonnegative, long integers over the range 0 <= y < 2 31 .

Opens a file for reading, writing, or editing. It positions the file at its beginning (byte 0).

Format

#include <fcntl.h>

int open (const char *file_spec, int flags, mode_t mode); (ANSI C)

int open (const char *file_spec, int flags, ...); (COMPAQ C EXTENSION)

Arguments

file_spec

A null-terminated character string containing a valid file specification. If you specify a directory in the file_spec and it is a search list that contains an error, Compaq C interprets it as a file open error.

flags

The following values are defined in the <file.h> header file:

O_RDONLY	Open for reading only
O_WRONLY	Open for writing only
O_RDWR	Open for reading and writing
O_NDELAY	Open for asynchronous input
O_APPEND	Append on each write
O_CREAT	Create a file if it does not exist
O_TRUNC	Create a new version of this file
O_EXCL	Error if attempting to create existing file

These flags are set using the bitwise OR operator (|) to separate specified flags.

Opening a file with O_APPEND causes each write on the file to be appended to the end. (In contrast, with the VAX C RTL the behavior of files opened in append mode was to start at EOF and, thereafter, write at the current file position.)

If O_TRUNC is specified and the file exists, open creates a new file by incrementing the version number by 1, leaving the old version in existence.

If O_CREAT is set and the named file does not exist, the Compaq C RTL creates it with any attributes specified in the fourth and subsequent arguments (...). If O_EXCL is set with O_CREAT and the named file exists, the attempted open returns an error.

mode

An unsigned value that specifies the file-protection mode. The compiler performs a bitwise AND operation on the mode and the complement of the current protection mode.

You can construct modes by using the bitwise OR operator (|) to separate specified modes. The modes are:

0400	OWNER:READ
0200	OWNER:WRITE
0100	OWNER:EXECUTE
0040	GROUP:READ
0020	GROUP:WRITE
0010	GROUP:EXECUTE
0004	WORLD:READ
0002	WORLD:WRITE
0001	WORLD:EXECUTE

The system is given the same access privileges as the owner. A WRITE privilege also implies a DELETE privilege.

...

Optional file attribute arguments. The file attribute arguments are the same as those used in the creat function. For more information, see the creat function.

Description

If a version of the file exists, a new file created with open inherits certain attributes from the existing file unless those attributes are specified in the open call. The following attributes are inherited: record format, maximum record size, carriage control, and file protection.

Notes If you intend to do random writing to a file, the file must be opened for update by specifying a flags value of O_RDWR . To create files with OpenVMS RMS default protections by using the UNIX system-call functions umask , mkdir , creat , and open , call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on. In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.

See also creat , read , write , close , dup , dup2 , and lseek in this section.

Return Values

x	A nonnegative file descriptor number.
- 1	Indicates that the file does not exist, that it is protected against reading or writing, or that it cannot be opened for another reason.

Example

#include <unixio.h> #include <file.h> #include <stdlib.h> main() { int file, stat; int flags; flags = O_RDWR; /* Open for read and write, */ /* with user default file protection, */ /* with max fixed record size of 2048, */ /* and a block size of 2048 bytes. */ file = open("file.dat", flags, 0, "rfm=fix", "mrs=2048", "bls=2048"); if (file == -1) perror("OPEN error"), exit(1); close(file); }

Opens a specified directory.

Format

#include <dirent.h>

DIR *opendir (const char *dir_name);

Argument

dir_name

The name of the directory to be opened.

Description

The opendir function opens the directory specifed by dir_name and associates a directory stream with it. The directory stream is positioned at the first entry. The type DIR , defined in the <dirent.h> header file, represents a directory stream. A directory stream is an ordered sequence of all the directory entries in a particular directory.

The opendir function also returns a pointer to identify the directory stream in subsequent operations. The NULL pointer is returned when the directory named by dir_name cannot be accessed, or when not enough memory is available to hold the entire stream.

Note An open directory must always be closed with the closedir function to ensure that the next attempt to open that directory is successful. The opendir function should be used with readdir , closedir , and rewinddir to examine the contents of the directory.

Example

See the program example in the description of closedir .

Return Values

x	A pointer to an object of type DIR .
NULL	Indicates an error; errno is set to one of the following values: EACCES -- Search permission is denied for any component of dir_name or read permission is denied for dir_name. ENAMETOOLONG -- The length of the dir_name string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX. ENOENT -- The dir_name argument points to the name of a file that does not exist, or is an empty string.

Nondestructively superimposes win1 on win2. The function writes the contents of win1 that will fit onto win2 beginning at the starting coordinates of both windows. Blanks on win1 leave the contents of the corresponding space on win2 unaltered. The overlay function copies as much of a window's box as possible.

Format

#include <curses.h>

int overlay (WINDOW *win1, WINDOW *win2);

Arguments

win1

A pointer to the window.

win2

A pointer to the window.

Return Values

OK	Indicates success.
ERR	Indicates an error.

Destructively writes the contents of win1 on win2.

Format

#include <curses.h>

int overwrite (WINDOW *win1, WINDOW *win2);

Arguments

win1

A pointer to the window.

win2

A pointer to the window.

Description

The overwrite function writes the contents of win1 that will fit onto win2 beginning at the starting coordinates of both windows. Blanks on win1 are written on win2 as blanks. This function copies as much of a window's box as possible.

Return Values

OK	Indicates success.
ERR	Indicates failure.

	privacy and legal statement
5763PRO_042.HTML