United States

Compaq C

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

Previous | Contents | Index

# memccpy

> Copies characters sequentially between strings in memory areas.

## Format

> #include <string.h>

> void *memccpy (void *dest, void *source, int c, size_t n);

Function Variants This function also has variants named `_memccpy32` and `_memccpy64` 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

> ### dest

> A pointer to the location of a destination string.

> ### source

> A pointer to the location of a source string.

> ### c

> A character that you want to search for.

> ### n

> The number of charcter you want to copy.

## Description

> This function operates on strings in memory areas. A memory area is a group of contiguous characters bound by a count and not terminated by a null character. The function does not check for overflow of the receiving memory area. The `memccpy` function is defined in the `<string.h>` header file.

> The `memccpy` function sequentially copies characters from the location pointed to by source into the location pointed to by dest until one of the following occurs:

> - The character specified by c (converted to an `unsigned char` ) is copied.
> - The number of characters specified by n is copied.

## Return Values

> x | A pointer to the character following the character specified by c in the string pointed to by dest.
> NULL | Indicates an error. The character c is not found after scanning n characters in the string.

# memchr

> Locates the first occurrence of the specified byte within the initial size bytes of a given object.

## Format

> #include <string.h>

> void *memchr (const void *s1, int c, size_t size);

Function Variants This function also has variants named `_memchr32` and `_memchr64` 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

> ### s1

> A pointer to the object to be searched.

> ### c

> The byte value to be located.

> ### size

> The length of the object to be searched.

> If size is zero, `memchr` returns NULL.

## Description

> Unlike `strchr` , the `memchr` function does not stop when it encounters a null character.

## Return Values

> pointer | A pointer to the first occurrence of the byte.
> NULL | Indicates that the specified byte does not occur in the object.

# memcmp

> Compares two objects, byte by byte. The compare operation starts with the first byte in each object.

## Format

> #include <string.h>

> int memcmp (const void *s1, const void *s2, size_t size);

## Arguments

> ### s1

> A pointer to the first object.

> ### s2

> A pointer to the second object.

> ### size

> The length of the objects to be compared.

> If size is zero, the two objects are considered equal.

## Description

> This function uses native byte comparison. The sign of the value returned is determined by the sign of the difference between the values of the first pair of unlike bytes in the objects being compared. Unlike the `strcmp` function, the `memcmp` function does not stop when a null character is encountered.

## Return Value

> x | An integer less than, equal to, or greater than 0, depending on whether the lexical value of the first object is less than, equal to, or greater than that of the second object.

# memcpy

> Copies a specified number of bytes from one object to another.

## Format

> #include <string.h>

> void *memcpy (void *dest, const void *source, size_t size);

Function Variants This function also has variants named `_memcpy32` and `_memcpy64` 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

> ### dest

> A pointer to the destination object.

> ### source

> A pointer to the source object.

> ### size

> The length of the object to be copied.

## Description

> This function copies size bytes from the object pointed to by source to the object pointed to by dest; it does not check for the overflow of the receiving memory area (dest). Unlike the `strcpy` function, the `memcpy` function does not stop when a null character is encountered.

## Return Value

> x | The value of dest.

# memmove

> Copies a specified number of bytes from one object to another.

## Format

> #include <string.h>

> void *memmove (void *dest, const void *source, size_t size);

Function Variants This function also has variants named `_memmove32` and `_memmove64` 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

> ### dest

> A pointer to the destination object.

> ### source

> A pointer to the source object.

> ### size

> The length of the object to be copied.

## Description

> In Compaq C for OpenVMS Systems, `memmove` and `memcpy` perform the same function. Programs that require portability should use `memmove` if the area pointed at by dest could overlap the area pointed at by source.

## Return Value

> x | The value of dest.

## Example

>     #include <string.h>
>     #include <stdio.h>

>     main()
>     {
>        char pdest[14] = "hello   there";
>        char *psource = "you are there";

>        memmove(pdest, psource, 7);
>        printf("%s\n", pdest);
>     }

> This example produces the following output:

>     you are there

# memset

> Sets a specified number of bytes in a given object to a given value.

## Format

> #include <string.h>

> void *memset (void *s, int value, size_t size);

Function Variants This function also has variants named `_memset32` and `_memset64` 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

> ### s

> An array pointer.

> ### value

> The value to be placed in s.

> ### size

> The number of bytes to be placed in s.

## Description

> This function copies value (converted to an `unsigned char` ) into each of the first `size` characters of the object pointed to by s.

> This function returns s. It does not check for the overflow of the receiving memory area pointed to by s.

## Return Value

> x | The value of s.

# mkdir

> Creates a directory.

## Format

> #include <stat.h>

> int mkdir (const char *dir_spec, mode_t mode); (ISO POSIX-1)

> int mkdir (const char *dir_spec, mode_t mode, ...); (DEC C EXTENSION)

## Arguments

> ### dir_spec

> A valid OpenVMS or UNIX style directory specification that may contain a device name. For example:

>     DBA0:[BAY.WINDOWS]     /*    OpenVMS      */
>     /dba0/bay/windows      /*   UNIX style    */

> This specification cannot contain a node name, file name, file extension, file version, or a wildcard character. The same restriction applies to the UNIX style directory specifications. For more information about the restrictions on UNIX style specifications, see Chapter 1.

> ### mode

> A file protection. See the `chmod` function in this section for information about the specific file protections.

> The file protection of the new directory is derived from the mode argument, the process's file protection mask (see the `umask` function), and the parent-directory default protections.

> In a manner consistent with the OpenVMS behavior for creating directories, `mkdir` never applies delete access to the directory. An application that needs to set delete access should use an explicit call to `chmod` to set write permission.

> See the Description section of this function for more information about how the file protection is set for the newly created directory.

> ### ...

> Represents the following optional arguments. These arguments have fixed position in the argument list, and cannot be arbitrarily placed.

> > `unsigned int` uic
> > The user identification code (UIC) that identifies the owner of the created directory. If this argument is 0, the Compaq C RTL gives the created directory the UIC of the parent directory. If this argument is not specified, the Compaq C RTL gives the created directory your UIC. This optional argument is specific to the Compaq C RTL and is not portable.
> > `unsigned short` max_versions
> > The maximum number of file versions to be retained in the created directory. The system automatically purges the directory keeping, at most, max_versions number of every file.
> > If this argument is 0, the Compaq C RTL does not place a limit on the maximum number of file versions.
> > If this argument is not specified, the Compaq C RTL gives the created directory the default version limit of the parent directory.
> > This optional argument is specific to the Compaq C RTL and is not portable.
> > `unsigned short` r_v_number
> > The volume (device) on which to place the created directory if the device is part of a volume set. If this argument is not specified, the Compaq C RTL arbitrarily places the created directory within the volume set. This optional argument is specific to the Compaq C RTL and is not portable.

## Description

> If dir_spec specifies a path that includes directories, which do not exist, intermediate directories are also created. This differs from the behavior of the UNIX system where these intermediate directories must exist and will not be created.

> If you do not specify any optional arguments, the Compaq C RTL gives the directory your UIC and the default version limit of the parent directory, and arbitrarily places the directory within the volume set. You cannot get the default behavior for the uic or max_versions arguments if you specify any arguments after them.

> Note The way to create files with OpenVMS RMS default protections using the UNIX system-call functions `umask` , `mkdir` , `creat` , and `open` is to 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.

> The file protection supplied by the mode argument is modified by the process's file protection mask in such a way that the file protection for the new directory is set to the bitwise AND of the mode argument and the complement of the file protection mask.

> Default file protections are supplied to the new directory from the parent-directory such that if a protection value bit in the new directory is zero, then the value of this bit is inherited from the parent-directory. However, bits in the parent directory's file protection that indicate delete access do not cause corresponding bits to be set in the new directory's file protection.

## Return Values

> 0 | Indicates success.
> --1 | Indicates failure.

##

### Examples

#1
    umask (0002); /* turn world write access off */
    mkdir ("sys$disk:[.parentdir.childdir]", 0222);  /* turn write access on */

    Parent directory file protection:  System:RWD, Owner:RWD, Group:R, World:R

> The file protection derived from the combination of the mode argument and the file protection mask set by `umask` is (0222) & ~(0002), which is 0220. When the parent directory defaults are applied to this protection, the protection for the new directory becomes:

>     File protection:    System:RWD, Owner:RWD, Group:RWD, World:R

#2
    umask (0000);
    mkdir ("sys$disk:[.parentdir.childdir]", 0444);  /* turn read access on */

    Parent directory file protection:  System:RWD, Owner:RWD, Group:RWD, World:RWD

> The file protection derived from the combination of the mode argument and the file protection mask set by `umask` is (0444) & ~(0000) which is 0444. When the parent directory defaults are applied to this protection, the protection for the new directory is:

>     File protection:    System:RW, Owner:RW, Group:RW, World:RW

> Note that delete access is not inherited.

# mkstemp

> Constructs a unique filename.

## Format

> #include <stdlib.h>

> int mkstemp (char *template);

## Arguments

> ### template

> A pointer to a string that is replaced with a unique filename. The string in the template argument must be a filename with six trailing Xs.

## Description

> This function replaces the six trailing Xs of the string pointed to by template with a unique set of characters, and returns a file descriptor for the file open for reading and writing.

> 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 filedes, off_t off); (X/OPEN, POSIX-1)

> void mmap (void *addr, size_t len, int prot, int flags, int filedes, off_t off ...); (DEC C EXTENSION)

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.

> ### ...

> An optional integer specifying additional flags for the SYS$CRMPSC system service for MAP_SHARED. This optional argument (Compaq C Extension) of the `mmap` function was introduced in OpenVMS Version 7.2.

## Description

> This function creates a new mapped file region, a new private region, or a new shared memory region.

> Your application must ensure correct synchronization when using `mmap` in conjunction with any other file access method, such as `read` and `write` , and standard input/output.

> Before calling `mmap` , the calling application must also ensure that all bytes in the range [off, off+len] are written to the file (using the `fsync` function, for example). If this requirement is not met, `mmap` fails with `errno` set to ENXIO (No such device or address).

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

> Previous | Next | Contents | Index

> privacy and legal statement