United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

If MAP_VARIABLE is set in the flags argument:

- If the requested address is null or if it is not possible for the system to place the region at the requested address, the region is placed at an address selected by the system.

If MAP_FIXED is set in the flags argument:

- If the requested address is not null, the `mmap` function succeeds even if the requested address is already part of another region. (If the address is within an existing region, the effect on the pages within that region and within the area of the overlap produced by the two regions is the same as if they were unmapped. In other words, whatever is mapped between addr and addr + len is unmapped.)
- If the requested address is null and MAP_FIXED is specified, the results are undefined.

The MAP_PRIVATE and MAP_SHARED flags control the visibility of modifications to the mapped file or shared memory region. One of these flags must be selected.

If MAP_SHARED is set in the flags argument:

- If the region is a mapped region, modifications to the region are visible to other processes that mapped the same region using MAP_SHARED.
- If the region is a mapped file region, modifications to the region are written to the file. (Note that the modifications are not immediately written to the file because of buffer cache delay; that is, the write to the file does not occur until there is a need to reuse the buffer cache. If the modifications must be written to the file immediately, use the `msync` function to ensure that this is done.)

If MAP_PRIVATE is set in the flags argument:

- Modifications to the mapped region by the calling process are not visible to other processes that mapped the same region using either MAP_PRIVATE or MAP_SHARED.
- Modifications to the mapped region by the calling process are not written to the file.

It is unspecified whether modifications by processes that mapped the region using MAP_SHARED are visible to other processes that mapped the same region using MAP_PRIVATE.

The prot argument specifies access permissions for the mapped region. Specify one of the following:

PROT_NONE | No access
PROT_READ | Read-only
PROT_WRITE | Read/Write access

After the successful completion of the `mmap` function, you can close the filedes argument without effect on the mapped region or on the contents of the mapped file. Each mapped region creates a file reference, similar to an open file descriptor, that prevents the file data from being deallocated.

Note The following rules apply to OpenVMS specific file references: Because of the additional file reference, if filedes is not opened for file sharing, `mmap` reopens it with file sharing enabled. The additional file reference that remains for mapped regions implies that a later `open` , `fopen` , or `create` call to the file that is mapped must specify file sharing.

Modifications made to the file using the `write` function are visible to mapped regions, and modifications to a mapped region are visible with the `read` function.

Note Beginning with OpenVMS Version 7.2, while processing a MAP_SHARED request, the `mmap` function constructs the flags argument of the SYS$CRMPSC service as a bitwise inclusive OR of those bits it sets by itself to fulfill the MAP_SHARED request and those bits specified by the caller in the optional argument. By default, for MAP_SHARED the `mmap` function creates a temporary group global section. The optional `mmap` argument provides the caller with direct access to the features of the SYS$CRMPSC system service. Using the optional argument, the caller can create, for example, a system global section (SEC$M_SYSGBL bit) or permanent global section (SEC$M_PERM bit). For example, to create a system permanent global section, the caller can specify (SEC$M_SYSGBL | SEC$M_PERM) in the optional argument. The `mmap` function does not check or set any privileges. So it is the responsibility of the caller to set appropriate privileges, such as SYSGBL privilege for SEC$M_SYSGBL, and PRMGBL for SEC$M_PERM, before calling `mmap` with the optional argument.

See also `read` , `write` , `open` , `fopen` , `creat` , and `sysconf` in this section.

## Return Values

> x | The address where the mapping is placed.
> MAP_FAILED | Indicates an error; `errno` is set to one of the following values: EACCES -- The file referred to by filedes is not open for read access, or the file is not open for write access and PROT_WRITE was set for a MAP_SHARED mapping operation. EBADF -- The filedes argument is not a valid file descriptor. EINVAL --The flags or prot argument is invalid, or the addr argument or off argument is not a multiple of the page size returned by `sysconf(_SC_PAGE_SIZE)` . Or MAP_ANONYMOUS was specified in flags and filedes is not --1. ENODEV -- The file descriptor filedes refers to an object that cannot be mapped, such as a terminal. ENOMEM -- There is not enough address space to map len bytes. ENXIO -- The addresses specified by the range [ off, off + len] are invalid for filedes. EFAULT -- The addr argument is an invalid address.

# modf

> Returns the positive fractional part of its first argument and assigns the integer part, expressed as an object of type `double` , to the object whose address is specified by the second argument.

## Format

> #include <math.h>

> double modf (double value, double *iptr);

## Arguments

> ### value

> Must be an object of type `double` .

> ### iptr

> A pointer to an object of type `double` .

# [w]move

> Change the current cursor position on the specified window to the coordinates (y,x). The `move` function acts on the `stdscr` window.

## Format

> #include <curses.h>

> int move (int y, int x);

> int wmove (WINDOW *win, int y, int x);

## Arguments

> ### win

> A pointer to the window.

> ### y

> A window coordinate.

> ### x

> A window coordinate.

## Description

> For more information, see the `scrollok` function in this section.

## Return Values

> OK | Indicates success.
> ERR | Indicates that the function makes the screen scroll illegally.

# mprotect

> Modifies access protections of memory mapping.

## Format

> #include <mman.h>

> int mprotect (void *addr, size_t len, int prot);

## Arguments

> ### addr

> The address of the region that you want to modify.

> ### len

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

> ### prot

> Access permission, as defined in the `<mman.h>` header file. Specify either PROT_NONE, PROT_READ, or PROT_WRITE.

## Description

> This function modifies the access protection of a mapped file or shared memory region.

> The addr and len arguments specify the address and length in bytes of the region that you want to modify. The len argument must be a multiple of the page size as returned by `sysconf(_SC_PAGE_SIZE)` . If len is not a multiple of the page size as returned by `sysconf(_SC_PAGE_SIZE)` , the length of the region is rounded up to the next multiple of the page size.

> The prot argument specifies access permissions for the mapped region. Specify one of the following:

> PROT_NONE | No access
> PROT_READ | Read-only
> PROT_WRITE | Read/Write access

> The `mprotect` function does not modify the access permission of any region that lies outside of the specified region, except that the effect on addresses between the end of the region, and the end of the page containing the end of the region, is unspecified.

> If the `mprotect` function fails under a condition other than that specified by EINVAL, the access protection of some of the pages in the range [addr, addr + len] can change. Suppose the error occurs on some page at an addr2; `mprotect` can modify protections of all whole pages in the range [addr, addr2].

> See also `sysconf` in this section.

## Return Values

> 0 | Indicates success.
> --1 | Indicates an error; `errno` is set to one of the following values: EACCESS -- The prot argument specifies a protection that conflicts with the access permission set for the underlying file. EINVAL -- The prot argument is invalid, or 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.

# mrand48

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

## Format

> #include <stdlib.h>

> long int mrand48 (void);

## Description

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

> It returns signed long integers uniformly distributed over the range of y values such that -231 <= y < 231 .

> Before you call the `mrand48` function, use either `srand48` , `seed48` , or `lcong48` to initialize the random number generator. You must initialize the `mrand48` function prior to invoking it, because it stores the last 48-bit Xi generated into an internal buffer. (Although it is not recommended, constant default initializer values are supplied automatically if the `drand48` , `lrand48` , or `mrand48` functions are called without first calling an initialization function.)

> 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 248 , 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 values returned by the `mrand48` function is computed by first generating the next 48-bit Xi in the sequence. Then the appropriate bits, according to the type of returned data item, are copied from the high-order (most significant) bits of Xi and transformed into the returned value.

> See also `drand48` , `lrand48` , `lcong48` , `seed48` , and `srand48` in this section.

## Return Values

> n | Returns signed long integers uniformly distributed over the range -2 31 <= y < 2 31 .

# msync

> 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

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

# munmap

> 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

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

# mv[w]addch

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

# mv[w]addstr

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

# mvcur

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

Previous | Next | Contents | Index

privacy and legal statement