Document revision date: 15 July 2002

Synchronizes a mapped file.

Format

#include <mman.h>

int msync (void *addr, size_t len, int flags);

Arguments

addr

The address of the region that you want to synchronize.

len

The length in bytes of the region that you want to synchronize.

flags

One of the following symbolic constants defined in the <mman.h> header file:

MS_SYNC	Synchronous cache flush
MS_ASYNC	Asynchronous cache flush
MS_INVALIDATE	Invalidate cashed pages

Description

The msync function controls the caching operations of a mapped file region. Use msync to:

• Ensure that modified pages in the region transfer to the underlying storage device of the file.
• Control the visibility of modifications with respect to file system operations.

The addr and len arguments specify the region to be synchronized. The len argument must be a multiple of the page size as returned by sysconf(_SC_PAGE_SIZE) ; otherwise, the length of the region is rounded up to the next multiple of the page size.

If the flags argument is set to:

flags Argument	Then the msync Function...
MS_SYNC	Does not return until the system completes all I/O operations.
MS_ASYNC	Returns after the system schedules all I/O operations.
MS_INVALIDATE	Invalidates all cached copies of the pages. The operating system must obtain new copies of the pages from the file system the next time the application references them.

After a successful call to the msync function with the flags argument set to:

• MS_SYNC -- All previous modifications to the mapped region are visible to processes using the read argument. Previous modifications to the file using the write function are lost.
• MS_INVALIDATE -- All previous modifications to the file using the write function are visible to the mapped region. Previous direct modifications to the mapped region are lost.

See also read , write , and sysconf in this section.

Return Values

0

Indicates success.

- 1

Indicates an error; errno is set to one of the following values: EIO -- An I/O error occurred while reading from or writing to the file system. ENOMEM -- The range specified by [ addr, addr + len] is invalid for a process' address space, or the range specifies one or more unmapped pages. EINVAL -- The addr argument is not a multiple of the page size as returned by sysconf(_SC_PAGE_SIZE) . EFAULT -- The range [ addr, addr + len] includes an invalid address.

Unmaps a mapped region.

Format

#include <mman.h>

int munmap (void *addr, size_t len);

Arguments

addr

The address of the region that you want to unmap.

len

The length in bytes of that region the you want to unmap.

Description

The munmap function unmaps a mapped file or shared memory region.

The addr and len arguments specify the address and length in bytes, respectively, of the region to be unmapped.

The len argument must be a multiple of the page size as returned by sysconf(_SC_PAGE_SIZE) ; otherwise, the length of the region is rounded up to the next multiple of the page size.

The result of using an address that lies in an unmapped region and not in any subsequently mapped region is undefined.

See also sysconf in this section.

Return Values

0	Indicates success.
- 1	Indicates an error; errno is set to one of the following values: ENIVAL -- The addr argument is not a multiple of the page size as returned by sysconf(_SC_PAGE_SIZE) . EFAULT -- The range [ addr, addr + len] includes an invalid address.

Move the cursor to coordinates (y,x) and add a character to the specified window.

Format

#include <curses.h>

int mvaddch (int y, int x, char ch);

int mvwaddch (WINDOW *win, int y, int x, char ch);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

ch

If this argument is a new-line character (\n), the mvaddch and mvwaddch functions clear the line to the end, and move the cursor to the next line at the same x coordinate. A carriage return (\r) moves the cursor to the beginning of the specified line. A tab (\t) moves the cursor to the next tabstop within the window.

Description

This routine performs the same function as mvwaddch , but on the stdscr window.

When mvwaddch is used on a subwindow, it writes the character onto the underlying window as well.

Return Values

OK	Indicates success.
ERR	Indicates that writing the character would cause the screen to scroll illegally. For more information, see the scrollok function in this section.

Move the cursor to coordinates (y,x) and add the specified string, to which str points, to the specified window.

Format

#include <curses.h>

int mvaddstr (int y, int x, char *str);

int mvwaddstr (WINDOW *win, int y, int x, char *str);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

str

A pointer to the character string.

Description

This routine performs the same function as mvwaddstr , but on the stdscr window.

When mvwaddstr is used on a subwindow, the string is written onto the underlying window as well.

Return Values

OK	Indicates success.
ERR	Indicates that the function causes the screen to scroll illegally, but it places as much of the string onto the window as possible. For more information, see the scrollok function in this section.

Moves the terminal's cursor from (lasty,lastx) to (newy,newx).

Format

#include <curses.h>

int mvcur (int lasty, int lastx, int newy, int newx);

Arguments

lasty

The cursor position.

lastx

The cursor position.

newy

The resulting cursor position.

newx

The resulting cursor position.

Description

In Compaq C for OpenVMS Systems, mvcur and move perform the same function.

See also move in this section.

Return Values

OK	Indicates success.
ERR	Indicates that moving the window put part or all of the window off the edge of the terminal screen. The terminal screen remains unaltered.

Move the cursor to coordinates (y,x) and delete the character on the specified window. The mvdelch function acts on the stdscr window.

Format

#include <curses.h>

int mvdelch (int y, int x);

int mvwdelch (WINDOW *win, int y, int x);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

Description

Each of the following characters on the same line shifts to the left, and the last character becomes blank.

Return Values

OK	Indicates success.
ERR	Indicates that deleting the character would cause the screen to scroll illegally. For more information, see the scrollok function in this section.

Move the cursor to coordinates (y,x), get a character from the terminal screen, and echo it on the specified window. The mvgetch function acts on the stdscr window.

Format

#include <curses.h>

int mvgetch (int y, int x);

int mvwgetch (WINDOW *win, int y, int x);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

Description

The mvgetch and mvwgetch functions refresh the specified window before fetching the character.

Return Values

x	The returned character.
ERR	Indicates that the function causes the screen to scroll illegally. For more information, see the scrollok function in this section.

Move the cursor to coordinates (y,x), get a string from the terminal screen, store it in the variable str (which must be large enough to contain the string), and echo it on the specified window. The mvgetstr function acts on the stdscr window.

Format

#include <curses.h>

int mvgetstr (int y, int x, char *str);

int mvwgetstr (WINDOW *win, int y, int x, char *str);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

str

The string that is displayed.

Description

The mvgetstr and mvwgetstr functions strip the new-line terminator (\n) from the string.

Return Values

OK	Indicates success.
ERR	Indicates that the function causes the screen to scroll illegally.

Move the cursor to coordinates (y,x) and return the character on the specified window without making changes to the window. The mvinch function acts on the stdscr window.

Format

#include <curses.h>

int mvinch (int y, int x);

int mvwinch (WINDOW *win, int y, int x);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

Return Values

x	The returned character.
ERR	Indicates an input error.

Move the cursor to coordinates (y,x) and insert the character ch into the specified window. The mvinsch function acts on the stdscr window.

Format

#include <curses.h>

int mvinsch (int y, int x, char ch);

int mvwinsch (WINDOW *win, int y, int x, char ch);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

ch

The character to be inserted at the window's coordinates.

Description

After the character is inserted, each character on the line shifts to the right, and the last character on the line is deleted.

Return Values

OK	Indicates success.
ERR	Indicates that the function makes the screen scroll illegally. For more information, see the scrollok function in this section.

Move the cursor to coordinates (y,x) and insert the specified string into the specified window. The mvinsstr function acts on the stdscr window.

Format

#include <curses.h>

int mvinsstr (int y, int x, char *str);

int mvwinsstr (WINDOW *win, int y, int x, char *str);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

str

The string that is displayed.

Description

Each character after the string shifts to the right, and the last character disappears. The mvinsstr and mvwinsstr functions are specific to Compaq C for OpenVMS Systems and are not portable.

Return Values

OK	Indicates success.
ERR	Indicates that the function makes the screen scroll illegally. For more information, see the scrollok function in this section.

Moves the starting position of the window to the specified (y,x) coordinates.

Format

#include <curses.h>

mvwin (WINDOW *win, int y, int x);

Arguments

win

A pointer to the window.

y

A window coordinate.

x

A window coordinate.

Description

When moving subwindows, the mvwin function does not rewrite the contents of the subwindow on the underlying window at the new position. If you write anything to the subwindow after the move, the function also writes to the underlying window.

Return Values

OK	Indicates success.
ERR	Indicates that moving the window put part or all of the window off the edge of the terminal screen. The terminal screen remains unaltered.

Creates a new window with numlines lines and numcols columns starting at the coordinates (begin_y,begin_x) on the terminal screen.

Format

#include <curses.h>

WINDOW *newwin (int numlines, int numcols, int begin_y, int begin_x);

Arguments

numlines

If it is 0, the newwin function sets that dimension to LINES (begin_y). To get a new window of dimensions LINES by COLS, use the following line:

newwin (0, 0, 0, 0)

numcols

If it is 0, the newwin function sets that dimension to COLS (begin_x). Thus, to get a new window of dimensions LINES by COLS, use the following line:

newwin (0, 0, 0, 0)

begin_y

A window coordinate.

begin_x

A window coordinate.

Return Values

x	The address of the allocated window.
ERR	Indicates an error.

Returns the next machine-representable number following x in the direction of y.

Format

#include <math.h>

double nextafter (double x, double y);

float nextafterf (float x, float y);

long double nextafterl (long double x, long double y);

Arguments

x

A real number.

y

A real number.

Description

The nextafter functions return the next machine-representable floating-point number following x in the direction of y. If y is less than x, nextafter returns the largest representable floating-point number less than x.

Return Values

x	The next representable floating-point value following x in the direction of y.
HUGE_VAL	Overflow; errno is set to ERANGE.
NaN	x or y is NaN; errno is set to EDOM.

Increases or decreases process priority relative to the process current priority by the amount of the argument. This function is nonreentrant.

Format

#include <unistd.h>

int nice (int increment);

Argument

increment

As a positive argument, decreases priority; as a negative argument, increases priority. Issuing nice(0) restores the base priority. The resulting priority cannot be less than 1, or greater than the process's base priority. If it is, the nice function quietly does nothing.

Description

When a process calls the vfork function, the resulting child inherits the parent's priority.

See also vfork in this section.

Return Values

0	Indicates success.
- 1	Indicates failure.

Returns the nearest integral value to the argument.

Format

#include <math.h>

double nint (double x);

float nintf (float x,);

long double nintl (long double x);

Argument

x

A real number.

Description

The nint functions return the nearest integral value to x, except halfway cases are rounded to the integral value larger in magnitude. This corresponds to the Fortran generic intrinsic function nint .

Return Values

n	The nearest integral value to x.
NaN	x is NaN; errno is set to EDOM.

	privacy and legal statement
5763PRO_041.HTML