HP OpenVMS Systems Documentation

Content starts here

Run-Time Library Reference Manual for OpenVMS Systems

Previous Contents Index

11.5 Sample Date/Time Scenario

The following example and explanation shows how to use the HP C RTL time functions to print the current time:

#include <stdio.h>
#include <time.h>

main ()
  time_t t;

  t = time((time_t)0);
  printf ("The current time is: %s\n",asctime (localtime (&t)));

This example:

  1. Calls the time function to get the current time in seconds since the Epoch, in terms of UTC.
  2. Passes this value to the localtime function, which uses time-conversion information as specified by tzset to determine which time-zone conversion rules should be used to compute local time from UTC. By default, these rules are specified in the file defined by SYS$LOCALTIME:
    1. For a user in the Eastern United States interested in their local time, SYS$LOCALTIME would be defined during installation to SYS$COMMON:[SYS$ZONEINFO.US]EASTERN, the time-zone file containing conversion rules for the Eastern U.S. time zone.
    2. If the local time falls during daylight savings time (DST), SYS$COMMON:[SYS$ZONEINFO.US]EASTERN indicates that a time differential factor of - 4 hours needs to be applied to UTC to get local time.
      If the local time falls during Eastern standard time (EST), SYS$COMMON:[SYS$ZONEINFO.US]EASTERN indicates that a time differential factor of - 5 hours needs to be applied to UTC to get local time.
    3. The HP C RTL applies - 4 (DST) or - 5 (EST) to UTC, and localtime returns the local time in terms of a tm structure.
  3. Pass this tm structure to the asctime function to print the local time in a readable format.

Chapter 12
Symbolic Links and POSIX Pathname Support

OpenVMS Version 8.3 and higher provides Open Group compliant symbolic link support and POSIX pathname processing support. This support will help partners and customers who port UNIX and LINUX applications to OpenVMS or who use a UNIX style development environment to reduce the application development costs and complexity previously associated with such porting efforts.

The following OpenVMS features are provided to support symbolic links and POSIX pathname processing:

  • The Open Group compliant symbolic-link functions symlink , readlink , unlink , realpath , lchown and lstat are added to the C Run-Time Library (C RTL) (see Section 12.3.3).
  • Existing C RTL functions such as creat , open , delete , and remove , now behave in accordance with Open Group specifications for symbolic links (see Section 12.3.4).
  • RMS allows the C RTL to implement the above-mentioned functions. RMS routines such as SYS$OPEN, SYS$CREATE, SYS$PARSE, and SYS$SEARCH now support symbolic links (see Section 12.4).
  • The contents of symbolic links on OpenVMS are interpreted as POSIX pathnames when encountered during pathwalks and searches. POSIX pathnames are now supported in OpenVMS and are usable through C RTL and RMS interfaces (see Section 12.1.2.)
  • A new feature logical DECC$POSIX_COMPLIANT_PATHNAMES is added to the C RTL to indicate that an application is operating in a POSIX-compliant mode. In POSIX-compliant mode, only the newest version of a file is visible. Access to multiple versions of a file is not allowed (see Section 12.3.1).
  • The DCL command CREATE/SYMLINK is used to create a symbolic link. (see Section 12.2.1).
  • The DCL command SET ROOT is used to create the system POSIX root (see Section 12.5).
  • Two GNV utilities, mnt and umnt , are provided to set mount points (see Section 12.7).
  • DCL commands and utilities are modified to behave appropriately when acting on and encountering symbolic links (see Section 12.9).
  • The TCP/IP Services for OpenVMS Network File System (NFS) client and server are enhanced to support symbolic links on ODS5 volumes.
  • Relevant GNV utilities such as ln (which can create a symbolic link) and ls (which can display the contents of a symbolic link) are updated to provide access to and management of symbolic links (see Sections 12.2.2 and 12.10).

12.1 POSIX Pathnames and Filenames

A POSIX pathname is a non-empty character string consisting of 0 or more filenames, separated by a / (the path delimiter). The path delimiter can be the first or last character of a pathname and is also the separator between filenames. Multiple consecutive delimiters are valid and are equivalent to a single delimiter.

POSIX filenames can consist of all ASCII characters except / (the path delimiter) and NUL, which is used as a string terminator in many APIs. (On OpenVMS systems, POSIX filenames are also currently restricted to not contain the ? or * character.) A filename is sometimes referred to as a pathname component.

12.1.1 POSIX Pathname Interpretation

If the pathname begins with a / , it is considered to be an absolute pathname, and pathname processing begins at the device and directory specified by the POSIX root (see Section 12.5 for the method to define the root).

If the pathname does not begin with a / , it is considered to be a relative pathname, and pathname processing begins with the current working directory.

See Section 12.6 for how OpenVMS interprets the current working directory. The POSIX Root Directory

The POSIX root directory is a directory that is used in pathname resolution for absolute pathnames.

The root directory, is the top-most node of the hierarchy, and has itself as its parent directory. The pathname of the root directory is / , and the parent directory of the root directory is / . Note that only files and directories actually entered in the root directory are accessible with a POSIX pathname. For additional details, see the note in Section 12.3.1.

See Section 12.5 for defining the POSIX root on OpenVMS. Symbolic Links

A symbolic link is a special kind of file that points to another file. It is a directory entry that associates a filename with a text string that is interpreted as a POSIX pathname when accessed by certain services. Most operations that access a symbolic link are rerouted to the object to which the text contents refer; if that object does not exist, the operation fails. A symbolic link is implemented on OpenVMS as a file of organization SPECIAL and type SYMBOLIC_LINK.

A symbolic link can specify an absolute pathname or a relative pathname. The relative path in a symbolic link is relative to the location of the link. For example, a symbolic link whose content begins with the path " .. " refers to its parent directory. If the symbolic link is moved to another directory, it refers to its new parent directory. Note that the path specified by a symbolic link is a POSIX pathname and is subject to the restrictions described in Section 12.3.1.

See Section 12.2 for symbolic link usage on OpenVMS. Mount Points

A mount point is a location (in fact, a directory) where a file system is attached. The UNIX term file system is essentially equivalent to the OpenVMS concept of a disk volume. After a mount point is established, any contents of the original directory are inaccessible.

Mount points do not persist across reboots.

See Section 12.7 for establishing mount points on OpenVMS. Reserved Filenames . and ..

There are two reserved POSIX filenames:

. (the current directory)

.. (the parent directory) Character Special Files

On UNIX systems, a special file is associated with a particular hardware device or other resource of the computer system. The operating system uses character special files, sometimes called device files, to provide I/O access to specific character devices.

Special files, at first glance, appear to be just like ordinary files, in that they:

  • Have path names that appear in a directory
  • Have the same access protection as ordinary files
  • Can be used in almost every way that ordinary files can be used

However, there is an important difference between the two: an ordinary file is a logical grouping of data recorded on disk, whereas a special file corresponds to a device entity. Examples are:

  • An actual device, such as a line printer
  • A logical subdevice, such as a large section of the disk drive
  • A pseudo device, such as the physical memory of the computer ( /dev/mem ), the terminal file ( /dev/tty ), or the null file ( /dev/null ).

Only the null special file ( /dev/null ) is supported. This file is created during the GNV configuration procedure. Data written on the null special file is discarded. Reads from a null special file always return 0 bytes.

12.1.2 Using POSIX Pathnames with OpenVMS Interfaces

POSIX compliant pathnames can be passed to most OpenVMS applications, utilities, and APIs.

The existing DCL convention of doubling any quote character that is in a quoted string has been adopted.

Also, in order to avoid constraints on future use of quoted strings for pathnames (for example, to support another syntactic variation, such as Windows-compatible names), the leading tag ^UP^ is required on the quoted pathname to identify it as a POSIX pathname to DCL, RMS, and OpenVMS utilities. It is not required for the C RTL or GNV.

So, for example, /a/b/c becomes "^UP^/a/b/c" and /a/b"/c becomes "^UP^/a/b""/c" .

Throughout the remainder of this chapter, the term POSIX pathname refers to the unmodified pathname (for example, /a/b/c ) and quoted pathname refers to our quoted, tagged pathname (for example, "^UP^/a/b/c" ). Special Considerations with POSIX Filenames

When a user creates a file on OpenVMS using a POSIX filename, it would be ideal if the filename viewed as an OpenVMS filename were the same. For example, when a user asks to create a file with POSIX filename a.b , OpenVMS could create a file with the name a.b; (where ; represents the file version).

But because one of the components of an OpenVMS filename is the file type (consisting of at least a period), POSIX filenames without a period cannot be mapped in as direct a fashion (for example, POSIX filename a cannot be mapped to OpenVMS filename a; ). The reasonable solution is for OpenVMS to append a period (representing a null file-type field) so that POSIX filename a becomes OpenVMS filename a.;

Note that OpenVMS appends a period (or null type) even to a POSIX filename that itself ends in a period. This is necessary to distinguish POSIX filenames a. and a from each other.

Furthermore, OpenVMS directories have a type and version of .DIR;1 . When a directory of POSIX filename a is created on OpenVMS, it is created with an OpenVMS filename of a.DIR;1 . And because a.DIR is a valid POSIX filename, it needs to be distinguished from a directory with POSIX filename a residing in the same directory. So OpenVMS adds a period (or null type) to POSIX filenames ending in .DIR (so a file with POSIX filename a.DIR becomes a.DIR.; ).

Keeping the above rules in mind, the following are POSIX filenames that are unmodified on OpenVMS, except for adding a version:

POSIX filename    OpenVMS name    Type    Version   Displayed by DIR as
--------------    ------------    ----    -------   -------------------
     a.b               a          .b         ;             a.b;
     a.b;              a          .b;        ;             a.b;;
     a.b;2             a          .b;2       ;             a.b;2;

The following are examples of POSIX filenames that end with a period (.) or .DIR and, therefore, have a period appended when creating the OpenVMS filename:

POSIX filename    OpenVMS name    Type    Version   Displayed by DIR as
--------------    ------------    ----    -------   -------------------
     a                 a           .         ;             a.;
     a.                a.          .         ;             a^..;
     a..               a..         .         ;             a^.^..;
     a.b.              a.b.        .         ;             a^.b^..;
     a.DIR             a.DIR       .         ;             a^.DIR.;

Finally, OpenVMS will add .DIR;1 to the end of any POSIX directory:

POSIX filename    OpenVMS name    Type    Version   Displayed by DIR as
--------------    ------------    ----    -------   -------------------
     a                a           .DIR      ;1           a.DIR;1
     a.dir            a.dir       .DIR      ;1           a^.dir.DIR;1
     a.               a.          .DIR      ;1           a^..DIR;1

Note that both the OpenVMS filenames a.DIR;1 and a.; map to the POSIX filename a . Specifying the POSIX filename a will find either a.DIR;1 or a.; . If both are present, it finds a.; . The ambiguous mapping applies whether a.DIR;1 is a directory or an ordinary file.

All POSIX filenames that contain the * or ? characters are unmappable. This is an open issue to be addressed in a future release of OpenVMS. Special Considerations with OpenVMS Filenames

When mapping OpenVMS filenames to POSIX filenames (a feature provided by C RTL function readdir ), the following rules apply:

If the OpenVMS filename ends in .DIR;1 and the type of a file is a directory, then .DIR;1 is removed. For all other files, the ending semi-colon and version number are removed from the OpenVMS filename.

If the OpenVMS filename ends in a period, the period is removed.

All OpenVMS filenames that contain the / or NUL characters are unmappable and, therefore, not returned to the caller.

OpenVMS directories ..DIR;1 and ...DIR;1 are unmappable because their corresponding POSIX filenames would be the special filenames . and .. .

OpenVMS file . is unmappable because the resulting POSIX filename would be a NULL string.

12.2 Using Symbolic Links

There are several ways to create a symbolic link:

12.2.1 Creating and Using Symbolic Links with DCL

The following examples show how to create and access symbolic links using DCL commands:



$ create/symlink="a/b.txt" link_to_b.txt
$ dir/date link_to_b.txt

Directory DKB0:[TEST]

link_to_b.txt -> a/b.txt
                  27-MAY-2005 09:45:15.20

This example creates the symbolic link file link_to_b.txt with contents equal to the specified text string representing the pathname to which the symbolic link points, a/b.txt . Note that a/b.txt may or may not exist. Also note that the symlink file must be reachable from the POSIX root.


$ type link_to_b.txt
  %TYPE-W-OPENIN, error opening DKB0:[TEST]LINK_TO_B.TXT; as input
 -RMS-E-FNF, file not found

To access the file referenced in a symbolic link, specify the symbolic link name on the command. The TYPE command error message in this example indicates that the file a/b.txt , referenced through the symbolic link link_to_b.txt created in the first example, does not exist.


  $ create [.a]b.txt
     This is a text file.
  $ type link_to_b.txt
  This is a text file

This example creates the missing file b.txt . Once the referenced file exists, the TYPE command through the symbolic link is successful.

Alternatively, you can create the file through the symbolic link:

$ create link_to_b.txt
   This is a text file.
$ dir [.a]

Directory DKB0:[TEST.A]

$ type link_to_b.txt
   This is a text file.

12.2.2 Using Symbolic Links through GNV POSIX and DCL Commands

You can create a symbolic link within the GNV bash shell with the ln utility:

bash$ ln -s filename slinkname

Most utilities and commands that reference slinkname are redirected so that they act on filename. Some commands, such as ls , are symbolic link-aware, and show information about the link itself (such as its contents).

A link can be removed with the rm command (which cannot be made to follow the link and remove what it points to).

The examples that follow show how to manage symbolic links through GNV POSIX commands as compared with DCL commands.



   From GNV:

     bash$ cd /symlink_example
     bash$ echo This is a test. > text
     bash$ cat text
     This is a test.
     bash$ ln -s text LINKTOTEXT

  From DCL:

     $ set def DISK$XALR:[PSX$ROOT.symlink_example]
     $ create text.
     This is a test.
     $ type text.
     This is a test.
     $ create/symlink="text" LINKTOTEXT

This example creates a symbolic link called LINKTOTEXT that points to a text file called text .


  From GNV:

     bash$ cat LINKTOTEXT
     This is a test.

  From DCL:

     $ type LINKTOTEXT.
     This is a test.

This example displays the contents of the text file using the symbolic link.


   From GNV:

     bash$ ls
     LINKTOTEXT  text
     bash$ ls -l
     total 1
     lrwxr-x---   1 SYSTEM   1        4 May 12 08:41 LINKTOTEXT -> text
     -rw-r-----   1 SYSTEM   1        16 May 12 08:40 text

  From DCL:

     $ DIR

     Directory DISK$XALR:[PSX$ROOT.symlink_example]

     LINKTOTEXT.;1       text.;1

     Total of 2 files.

     $ DIR/DATE

     Directory DISK$XALR:[PSX$ROOT.symlink_example]

     LINKTOTEXT.;1 -> /symlink_example/text
                     12-MAY-2005 08:46:31.40
     text.;1         12-MAY-2005 08:43:47.53

     Total of 2 files.

This example displays the content of a symbolic link. Notice that when you do an ls or a DIR using switches that show any file attribute, then the content of the symbolic link is also displayed.


   From GNV:

      bash$ rm text
      bash$ cat LINKTOTEXT
      cat: linktotext: i/o error
      bash$ rm LINKTOTEXT

   From DCL:

     $ DEL text.;1
     %TYPE-W-OPENIN, error opening
     DISK$XALR:[PSX$ROOT.symlink_example]LINKTOTEXT.;1 as input
     -RMS-E-ACC, ACP file access failed
     -SYSTEM-F-FILNOTACC, file not accessed on channel


This example deletes files.

12.3 C RTL Support

The following sections describe POSIX-compliant pathname and symbolic link support in the C RTL.

Previous Next Contents Index