DEC C
Run-Time Library Reference Manual for OpenVMS Systems

The string pointed to by template should look like a file name with six trailing X's. The mkstemp function replaces each X with a character from the portable file-name character set, making sure not to duplicate an existing file name.

If the string pointed to by template does not contain six trailing Xs, --1 is returned.

Return Values

x An open file descriptor.

--1 Indicates an error. (The string pointed to by template does not contain six trailing Xs.)

mktemp

Creates a unique file name from a template.

Format

#include <stdlib.h>
char *mktemp (char *template);

Function Variants This function also has variants named _mktemp32 and _mktemp64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

ARGUMENT

template
A pointer to a buffer containing a user-defined template. You supply the template in the form, namXXXXXX. The six trailing Xs are replaced by a unique series of characters. You may supply the first three characters. Because the template argument is overwritten, do not specify a string literal ( const object).

DESCRIPTION

The use of mktemp is not recommended for new applications. See the tmpnam and mkstemp functions for the preferable alternatives.

Return Value

x A pointer to the template, with the template modified to contain the created file name. If this value is a pointer to a null string, it indicates that a unique file name cannot be created.

mktime

Converts a local-time structure into time since the Epoch.

Format

#include <time.h>
time_t mktime (struct tm *timeptr);

Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to this function that is equivalent to the behavior before OpenVMS Version 7.0.

ARGUMENT

timeptr
A pointer to the local time structure.

DESCRIPTION

This function converts the local-time structure, pointed to by timeptr, to a time in seconds since the Epoch in the same manner as the values returned by the time function. If the local time cannot be encoded, then mktime returns the value ( time_t )(--1).
The time_t type is defined in the <time.h> header file as follows:
typedef unsigned long int time_t;
Local time-zone information is set as if mktime called tzset .
If the tm_isdst field in the local-time structure pointed to by timeptr is positive, mktime initially presumes that Daylight Savings Time (DST) is in effect for the specified time.
If tm_isdst is 0, mktime initially presumes that DST is not in effect.
If tm_isdst is negative, mktime attempts to determine whether or not DST is in effect for the specified time.

Return Values

x The specified calendar time encoded as a value of type time_t .

( time_t )(--1) If the local time cannot be encoded.
Be aware that a return value of ( time_t )(--1) can also represent the valid date: Sun Feb 7 06:28:15 2106.

mmap

Maps file system object into virtual memory.

Format

#include <types.h>
#include <mman.h>
void mmap (void *addr, size_t len, int prot, int flags, int filesdes, off_t off);

Function Variants This function also has variants named _mmap32 and _mmap64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

ARGUMENTS

addr
The starting address of the new region (truncated to a page boundary).
len
The length in bytes of the new region (rounded up to a page boundary).
prot
Access permission, as defined in the <mman.h> header file. Specify either PROT_NONE, PROT_READ, or PROT_WRITE.
flags
Attributes of the mapped region as the results of a bitwise-inclusive OR operation on any combination of the following:

MAP_FILE or MAP_ANONYMOUS
MAP_VARIABLE or MAP_FIXED
MAP_SHARED or MAP_PRIVATE

filedes
The file that you want to map to the new mapped file region returned by the open function.
off
The offset into the file that gets mapped at address addr.

DESCRIPTION

This function creates a new mapped file region, a new private region, or a new shared memory region.
The addr and len arguments specify the requested starting address and length in bytes for the new region. The address is a multiple of the page size returned by sysconf(_sc_page_size) .
If the len argument is not a multiple of the page size returned by sysconf(_sc_page_size) , then the result of any reference to an address between the end of the region and the end of the page containing the end of the region is undefined.
The flags argument specifies attributes of the mapped region. Values for flags are constructed by a bitwise-inclusive OR operation on the flags from the following list of symbolic names defined in the <mman.h> header file:

MAP_FILE Create a mapped file region.

MAP_ANONYMOUS Create an unnamed memory region.

MAP_VARIABLE Place region at the computed address.

MAP_FIXED Place region at fixed address.

MAP_SHARED Share changes.

MAP_PRIVATE Changes are private.

The MAP_FILE and MAP_ANONYMOUS flags control whether the region you want to map is a mapped file region or an anonymous shared memory region. One of these flags must be selected.
If MAP_FILE is set in the flags argument:

A new mapped file region is created, mapping the file associated with the filedes argument.
The off argument specifies the file byte offset where the mapping starts. This offset must be a multiple of the page size returned by sysconf(_sc_page_size) .
If the end of the mapped file region is beyond the end of the file, the result of any reference to an address in the mapped file region corresponding to an offset beyond the end of the file is unspecified.

If MAP_ANONYMOUS is set in the flags argument:

A new memory region is created and initialized to all zeros.
If the filedes argument is not --1, the mmap function fails.

The new region is placed at the requested address if the requested address is not null and it is possible to place the region at this address. When the requested address is null or the region cannot be placed at the requested address, the MAP_VARIABLE and MAP_FIXED flags control the placement of the region. One of these flags must be selected.
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.
See also read , write , open , fopen , creat , and sysconf in this section.

Return Values

x The address where the mapping is placed.

(caddr_t) --1 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 -2^³¹ <= y < 2^³¹ .
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 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 = 5DEECE66D₁₆ = 273673163155₈ c = B₁₆ = 13₈
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^ ³¹ <= y < 2^ ³¹ .

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.

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.

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

Previous Next Contents Index

x	An open file descriptor.
--1	Indicates an error. (The string pointed to by template does not contain six trailing Xs.)

x	The specified calendar time encoded as a value of type `time_t` .
( `time_t` )(--1)	If the local time cannot be encoded. Be aware that a return value of ( `time_t` )(--1) can also represent the valid date: Sun Feb 7 06:28:15 2106.

MAP_FILE	Create a mapped file region.
MAP_ANONYMOUS	Create an unnamed memory region.
MAP_VARIABLE	Place region at the computed address.
MAP_FIXED	Place region at fixed address.
MAP_SHARED	Share changes.
MAP_PRIVATE	Changes are private.

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

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

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

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.

DEC CRun-Time Library Reference Manual for OpenVMS Systems

Return Values

mktemp

Format

ARGUMENT

template

DESCRIPTION

Return Value

mktime

Format

ARGUMENT

timeptr

DESCRIPTION

Return Values

mmap

Format

ARGUMENTS

addr

len

prot

flags

filedes

off

DESCRIPTION

Return Values

modf

Format

ARGUMENTS

value

iptr

[w]move

Format

ARGUMENTS

win

y

x

DESCRIPTION

Return Values

mprotect

Format

ARGUMENTS

addr

len

prot

DESCRIPTION

Return Values

mrand48

Format

DESCRIPTION

Return Values

msync

Format

ARGUMENTS

addr

len

flags

DESCRIPTION

Return Values

munmap

Format

ARGUMENTS

addr

len

DESCRIPTION

Return Values

mv[w]addch

Format

ARGUMENTS

win

y

x

ch

DESCRIPTION

DEC C
Run-Time Library Reference Manual for OpenVMS Systems