HP OpenVMS Systems Documentation

Content starts here

Run-Time Library Reference Manual for OpenVMS Systems

Previous Contents Index


In order for a POSIX-compliant user to have consistency between the pathnames stored in symbolic links and the pathnames used as input to C RTL functions, the C RTL provides a feature logical, DECC$POSIX_COMPLIANT_PATHNAMES, to allow an application to present POSIX-compliant pathnames to any C RTL function that accepts a pathname.

By default DECC$POSIX_COMPLIANT_PATHNAMES is disabled, and the usual C RTL behavior prevails. Notice that this disabled mode includes interpretation of pathnames as UNIX style specifications and uses rules that are different and unrelated to POSIX-compliant pathname processing.

To disable DECC$POSIX_COMPLIANT_PATHNAMES when necessary, DEFINE it to 0 or "DISABLE":


To enable DECC$POSIX_COMPLIANT_PATHNAMES, set it to one of the following values:

1 POSIX only - All pathnames are designated as POSIX style.
2 Leans POSIX - Pathnames that end in " : " or contain any of the bracket characters " []<> ", and that can be successfully parsed by the SYS$FILESCAN service, are designated as OpenVMS style. Otherwise, they are designated as POSIX style.
3 Leans OpenVMS - The pathnames " . " and " .. ", or pathnames that contain " / " are designated as POSIX style. Otherwise, they are designated as OpenVMS style.
4 OpenVMS only - All pathnames are designated as OpenVMS style.


Modes 1 and 4 are not recommended because of interactions with other shareable libraries and utilities.

With DECC$POSIX_COMPLIANT_PATHNAMES thus enabled, the C RTL examines pathnames to determine if they should be designated as POSIX style or OpenVMS style, following rules determined by the value assigned to DECC$POSIX_COMPLIANT_PATHNAMES.

For example, to designate that most pathnames are to be POSIX-compliant:


When the C RTL designates a pathname as POSIX style, it does not convert a POSIX pathname it receives into an OpenVMS file specification; instead, it converts the POSIX pathname into the quoted pathname format (previously described) and allows RMS to process the pathname as it would process a pathname found in a symbolic link.


Under OpenVMS, the C RTL has historically provided additional functionality to UNIX programs: if a filename (or pathname) was given with an initial slash (/), and the C RTL could not find the named file under the root, it would attempt to translate the name immediately following the slash as a logical name or a device name. For example, the filename /SYS$COMMON/SYSEXE/DCL.EXE refers to DCL.EXE in SYS$COMMON:[SYSEXE]. Another example: /$1$DKA500 refers to the device $1$DKA500:. With DECC$POSIX_COMPLIANT_PATHNAMES defined, logical names and device names are not supported. The only names that are valid are names of files and directories actually present in the root. This restriction will be removed in a future release of OpenVMS.

Some older OpenVMS applications may depend on this older format. If you run such applications, you may want to place either symbolic links or mount points under the root to allow such filenames to continue to work.

When DECC$POSIX_COMPLIANT_PATHNAMES is defined, the following C RTL feature logicals are ignored:


12.3.2 decc$to_vms, decc$from_vms, and decc$translate_vms

When operating in POSIX-compliant mode, the C RTL function decc$to_vms converts a POSIX pathname into the RMS quoted pathname format. If an RMS quoted pathname is passed to either decc$from_vms or decc$translate_vms , these functions change the quoted pathname into a POSIX pathname by removing the quotes and the ^UP^ prefix (so, for example, "^UP^a/b" becomes a/b ). When not in POSIX-compliant mode, these functions operate as they did previously.

12.3.3 Symbolic Link Functions

Table 12-1 lists and describes the symbolic-link functions in the HP C Run-Time Library (RTL). For more detailed information on each function, see the Reference Section.

Table 12-1 Symbolic Link Functions
Function Description
lchown Changes the owner and/or group of a file. If the file is a symbolic link, the owner of the symbolic link is modified (in contrast to chown which would modify the file that the symbolic link points to).
lstat Retrieves information about the specified file. If the file is a symbolic link, information about the link itself is returned (in contrast to stat , which would return information about the file that the symbolic link points to).
readlink Reads the contents of a symbolic link and places them into a user-supplied buffer.
realpath Returns an absolute pathname from the POSIX root. This function is only supported in POSIX-compliant modes; that is, with DECC$POSIX_COMPLIANT_PATHNAMES enabled.
unlink Deletes a symbolic link from the system.
symlink Creates a symbolic link containing the specified contents.

12.3.4 Modifications to Existing Functions

In addition to the previously described new functions, the following C RTL functions are modified to support symbolic links:

When a new version of a file is created, and the named file already exists as a symbolic link, the file to which the symbolic link refers is created.

If the file_spec parameter refers to a symbolic link, the open function opens the file pointed to by the symbolic link.

delete , remove
When delete or remove is used to delete a symbolic link, the link itself is deleted, not the file to which it refers.

Also, in accordance with the Open Group specification, an errno value of ELOOP is returned if a loop exists in the resolution of a symbolic link.

12.3.5 Non POSIX-Compliant Behavior Multiple Versions of Files

When using POSIX-compliant pathnames, if multiple versions of a file exist, you can access only the latest version of the file. Deleting a file results in the deletion of only the highest-numbered version of a file. Ambiguous Filenames

If the file "a" and directory "a.DIR;1" both exist in a directory, users in POSIX-compliant mode will have the following access:

  • Functions that take only a directory name as input (such as chdir and opendir ) will return an error (ENOEXIST).
  • Functions whose input is a non-directory file (such as open ) will act on the non-directory file.
  • Functions whose input can be either a file or a directory (such as stat ) will act on the non-directory file.
  • readdir will return entries for both the file and the directory. POSIX Security Behavior for File Deletion

The OpenVMS C RTL library follows traditional OpenVMS security rules for permitting the deletion or unlinking of files and uses the protection on the files or links, whereas the POSIX security behavior for deleting files is to follow the security settings for the parent directory of the files or links.

To get the POSIX security behavior, files in a directory must have an Access Control Entry (ACE) placed on them that always grants delete access to those files by the class of users or programs that you want to have this behavior. You may also want to create a default protection ACE on the parent directory so newly created files get the desired behavior.

Please consult the HP OpenVMS Guide to System Security for more information on how to manage Access Control Entries.

12.4 RMS Interface

12.4.1 RMS Input/Output of POSIX Pathnames

As previously described, a quoted pathname is a POSIX pathname prefixed with the tag string ^UP^ and enclosed with opening and closing quotation marks. In addition, any quotation marks present in the POSIX pathname need to be doubled, consistent with the way DCL handles quoted strings.

Quoted pathnames are allowed in the primary name, default name, and/or related names. By identifying the ^UP^ prefix and the opening and closing quotation marks, RMS interprets the rest of the characters as a standard POSIX pathname (with the exception that every pair of quotation marks in the pathname is treated as a single quotation mark). If RMS detects a quoted pathname, then the expanded and resultant file specifications are supplied by RMS as quoted pathnames as well.

The components of the returned quoted pathname are referenced by the NAM or NAML as follows:

  • The node is NULL
  • The dev is "^UP^
  • The dir consists of all characters between the dev string up to and including the final slash (/)
  • The name consists of all characters following the dir up to the final period (.) (If there is no final period, the name consists of all characters following the dir up to the closing double quote (") )
  • The type consists of all characters following the name up to the closing double quote (")
  • The version is double quote (")

The dir, name, and type fields can be NUL.

For example, the quoted pathname "^UP^/a/b.c" consists of the following components:

The node is NUL
The dev is "^UP^
The dir is /a/
The name is b
The type is .c
The version is "

The following RMS routines support symbolic links:

  • SYS$OPEN operates on the target file pointed to by the symbolic link.
  • SYS$CREATE creates the file pointed to by the symbolic link.
  • SYS$PARSE analyzes the file specification string and fills in various NAM block fields.
  • SYS$SEARCH returns the DVI and FID of the target file. The DID is zero. The resultant name is that of the symbolic link and not the target file.
  • Setting NAML$V_OPEN_SPECIAL causes SYS$OPEN and SYS$SEARCH to not follow the symbolic link.

The following restrictions apply to RMS processing of POSIX pathnames:

  • If the primary file specification is a quoted pathname, then SYS$SEARCH returns only one file; in pathnames, no characters are defined as being wildcards.
  • If the primary file specification is a quoted pathname, then the default and related specifications are ignored.
  • If the primary file specification is a traditional OpenVMS file specification, then the default specification can be a quoted pathname; however, only the file name and type are used from the default specification.

12.4.2 Application Control of RMS Symbolic Link Processing

Applications, including DCL commands and utilities, need the ability to control RMS behavior when RMS encounters symbolic links during typical file operations. Specifically, applications need to be able to specify whether or not a pathname stored in a symbolic link should be included as part of pathname processing and directory searches. Furthermore, applications need to be able to specify different behavior depending on how the symbolic link is encountered.

A NAML$L_INPUT_FLAGS flag is now provided to allow necessary application flexibility:

  • If SYS$OPEN is supplied a pathname that is a symbolic link, the default behavior is to open the file specified by the pathname stored in the symbolic link. If the flag NAML$V_OPEN_SPECIAL is set, then the symbolic link file itself is opened.
  • If the result of a call to SYS$SEARCH is a symbolic link and the flag NAML$V_OPEN_SPECIAL is set, the DVI/FID of the symbolic link itself is returned. Otherwise, the default behavior is that the DVI/FID of the file specified by the pathname stored in the symbolic link is returned, unless that pathname is also a symbolic link, in which case the process is repeated until a non-symbolic link is reached before returning the DVI/FID.
  • When SYS$SEARCH performs wildcard directory lookups, then any symbolic links encountered are not examined to determine if they refer to directories.

12.5 Defining the POSIX Root

For absolute POSIX pathnames, RMS needs to interpret the leading ' / ' as a UNIX-style root. POSIX expects that everything starts from this POSIX root. The POSIX root can be established with the GNV installation procedure or with the new DCL command, SET ROOT.

12.5.1 Suggested Placement of the POSIX Root

During the GNV installation and configuration procedure or when using the SET ROOT command, you need to provide a location for the POSIX root for the system. By default, the GNV installation establishes the location of the root at SYS$SYSDEVICE:[PSX$ROOT]. You can accept this directory as the root or specify another directory. GNV then optionally creates a mount point in " /mnt " (which is directory " mnt " in your POSIX root directory) for each disk device on your system.

If you accept the default for the root, or specify any other directory that is not the top-level directory of a device, then files that do not reside in the directory tree under the root directory will be inaccessible using a POSIX pathname, unless the device containing the root directory is mounted by means of a mount point under the root. (This mount point is optionally generated by GNV during the configuration.) Be aware, though, that when such a mount point is created, directory tree traversals can result in a loop. See Figure 12-1.

Figure 12-1 POSIX Root Placement

         DKB0 -> 000000
             |                |
          PSX$ROOT         other things
       |          |           |
     DKB1       DKB2        DKB0
                        |                |
                    PSX$ROOT         other things

An alternative is to specify the top-level directory, the Master File Directory (MFD), of a device as the root and not create a mount point for that device. This makes all of the files on the device accessible via POSIX pathnames. However, using the MFD of a device (especially the system device) as the root means that all of the files in the MFD are visible when a user displays the files in a root directory (such as "ls /"). GNV users will see OpenVMS files that they might not expect to see; similarly, DCL users will see UNIX files they might not expect to see. Also, the MFD of a device might not be accessible to most general users, resulting in unexpected failures.

We recommend you use the supplied default root directory.

For more information on mount points, see Section 12.7.

12.5.2 The SET ROOT Command

The SET ROOT command has the following format:

SET ROOT  device-name:directory-spec

This command defines the POSIX root. In POSIX pathname processing mode, RMS and the C RTL will treat the leading ' / ' of a pathname as referring to the defined root. By default, the root is SYS$SYSDEVICE:[PSX$ROOT].

The root definition does not persist across a reboot.

The SET ROOT command has the following qualifier:

/LOG (default)


Controls whether the SET ROOT command displays a success indication after the root definition is set.

12.5.3 The SHOW ROOT Command

The SHOW ROOT command displays the current value of the system root and, if defined, the process root.

This command has the following format:


12.6 Current Working Directory

On UNIX systems, the current working directory is a directory that is used in pathname resolution for pathnames that do not begin with a slash.

If RMS encounters a symbolic link, the directory in which the symbolic link is found is the current working directory for the purposes of pathname resolution.

For the resolution of POSIX pathnames passed directly to RMS, the current working directory is the current OpenVMS default directory for the process. If the OpenVMS default directory is not a single directory (for example, the directory specification includes a search list), then the current working directory is the first directory encountered through the search list.

12.7 Establishing Mount Points

Two new utilities, mnt and umnt provide a way for a user to mount and dismount file systems from mount points. Only users who have CMKRNL privilege can mount and dismount file systems. These utilities are shipped as part of GNV.

The utilities maintain their own logical name table of mount points, which is used to display currently available mount points upon request.

The interfaces for these utilities are as follows:

List existing mount points.

mnt file_system mount_point
Mount file system file_system on mount point mount_point.

umnt mount_point
Unmount the file system mounted on mount point mount_point.

umnt file_system
Unmount the file system file_system from its mount point.

umnt -A
Unmount all file systems from their mount points.

Note that both OpenVMS file specifications and POSIX pathnames are allowed for the arguments.

12.8 NFS

In TCP/IP Services for OpenVMS, Version 5.4 and older, there was limited symbolic link support in the NFS client for the purpose of backing up symbolic links from a UNIX server into an OpenVMS saveset and correctly restoring them. The client used an application ACE to flag a file as a symbolic link. In Version 5.5, the client preserves this behavior for an ODS-2 mount. For an ODS-5 mount, it creates a symbolic link when it sees the application ACE. This allows savesets created with older versions of the client to still be restored with newer versions.

12.9 DCL

OpenVMS DCL commands and utilities behave in predictable ways when encountering symbolic links. Usually, the symbolic link is followed; for example, if symbolic link LINKFILE.TXT points to file TEXT.TXT, then entering the command "type LINKFILE.TXT" displays the text contained in TEXT.TXT.

The symbolic link is followed even if the symbolic link itself is not directly specified; for example, if a symbolic link that references a directory is encountered when processing a command such as " dir [...]*.TXT ", any files with a type of " .TXT " that exist in the pointed-to directory (and its subdirectories) would be displayed. (Note: For OpenVMS Version 8.3, during directory wildcard operations, symbolic links are not examined to see if they refer to directories.)

There are some cases, however, where the symbolic link should not be followed by default. Also, it is sometimes desirable to give the user the option of whether or not to follow a symbolic link.

The following commands either do not follow the symbolic link by default and/or provide an option whether or not to follow a symbolic link.

When a symbolic link is encountered during a backup operation, the symbolic link itself is copied. This is true for all backup types---physical, image and file.

If an input file is a symbolic link, the file referred to by the symbolic link is the file that is copied.
The /SYMLINK qualifier indicates that any input symbolic link is copied.

Creates a symbolic link containing the specified text without the enclosing quotation marks.
If the created symbolic link is subsequently encountered during any filename processing, the contents of the symbolic link are read and treated as a POSIX pathname specification.
No previous version of the symbolic link can exist.

If an input file specification parameter is a symbolic link, the symbolic link itself is deleted.

If an input file specification parameter is a symbolic link, the displayed file attributes are those of the symbolic link itself. If any file attribute is requested, then the contents of the symbolic link are also displayed with an arrow appearing between the filename and the contents (for example, LINK.TXT -> FILE.TXT).
The /NOSYMLINK qualifier indicates that if an input file specification is a symbolic link, then the file attributes of the file to which the symbolic link refers are displayed; the displayed name is still the name of the symbolic link itself.

If an input file is a symbolic link, the file referred to by the symbolic link is the file that is dumped.
The /SYMLINK qualifier indicates that any input symbolic link is dumped.

If an input file specification is a symbolic link, the symbolic link itself is purged. Because only one version of a symbolic link can exist, this command has no effect on that file.

If an input file specification is a symbolic link, the symbolic link itself is renamed.
If the output file specification is a symbolic link, the operation fails.

If an input file is a symbolic link, the file referred to by the symbolic link is the file that is set.
The /SYMLINK qualifier indicates that the symbolic link itself is set.


  • The /EXCLUDE qualifier excludes symbolic links that match the qualifer's file specification of files to be excluded. The filename of a file that is referred to by a symbolic link is not excluded on the basis of its own name.


    If symbolic link LINK.TXT refers to TEXT.TXT in another directory, then:
    /EXCLUDE=LINK.TXT would exclude LINK.TXT (and, therefore, TEXT.TXT) from the operation.

    /EXCLUDE=TEXT.TXT would not exclude LINK.TXT or TEXT.TXT from the operation.
  • Given a symbolic link, F$FILE_ATTRIBUTES acts on the file to which the symbolic link refers. A new lexical function, F$SYMLINK_ATTRIBUTES, returns information on the symbolic link itself. New lexical function F$READLINK returns the text contents of a symbolic link, and NULL if the input is not a symbolic link.
  • Some compilers and utilities will accept quoted pathnames as input file specifications and as arguments to qualifiers. These include the C and C++ compilers, CXXLINK, the Linker, and the Librarian. Linker option files can also contain quoted pathnames. Note that the /INCLUDE_DIRECTORY qualifier for the compilers continues to accept standard POSIX pathnames rather than the quoted pathnames. The Java compiler also continues to accept standard POSIX pathnames. In addition, SET DEFAULT accepts quoted pathnames as input.

Previous Next Contents Index