HP OpenVMS Systems Documentation

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);

Arguments

s

An array pointer.

value

The value to be placed in s.

size

The number of bytes to be placed in s.

Description

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

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, ...); (HP 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, filename, 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 HP C RTL gives the created directory the UIC of the parent directory. If this argument is not specified, the HP C RTL gives the created directory your UIC. This optional argument is specific to the HP 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 HP C RTL does not place a limit on the maximum number of file versions.
If this argument is not specified, the HP C RTL gives the created directory the default version limit of the parent directory.
This optional argument is specific to the HP 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 HP C RTL arbitrarily places the created directory within the volume set. This optional argument is specific to the HP 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 HP 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

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

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.

Constructs a unique filename.

Format

#include <stdlib.h>

int mkstemp (char *template);

Argument

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

The mkstemp 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 filename 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 filename.

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

Creates a unique filename from a template.

Format

#include <stdlib.h>

char *mktemp (char *template);

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 filename. If this value is a pointer to a null string, it indicates that a unique filename cannot be created.

Converts a local-time structure to a time, in seconds, since the Epoch.

Format

#include <time.h>

time_t mktime (struct tm *timeptr);

Argument

timeptr

A pointer to the local-time structure.

Description

The mktime function converts a local-time structure ( struct tm ) pointed to by timeptr, to a time in seconds since the Epoch (a time_t variable), in the same manner as the values returned by the time function.

The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges defined in <time.h> . Upon successful completion, the tm_wday and tm_yday components of the structure are set appropriately, and the other components are set to represent the specified time, with their values forced to the normal range.

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.

Maps file system object into virtual memory. This function is reentrant.

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 ...); (HP C EXTENSION)

Arguments

addr

The starting address of the new region (must be the page boundary).

len

The length, in bytes, of the new region.

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, specified in bytes. The off_t data type is either a 64-bit or 32-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and can be selected at compile time by defining the _LARGEFILE feature-test macro as follows:

CC/DEFINE=_LARGEFILE

...

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

Description

The mmap 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.
• The filedes argument is ignored.

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.

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

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