pathnames_ccase

Path name resolution, dynamic view context, and extended namespace

Applicability

Product

Command type

ClearCase®

general information

Platform

UNIX

Linux

Windows

Synopsis

  • VOB-extended path name:

    Element

    element-pname@@

    Branch

    element-pname@@branch-pname

    Version

    element-pname@@version-selector

    VOB symbolic link

    link-pname

    Derived object

    derived-object-pname@@derived-object-ID

  • UNIX and Linux dynamic views—Absolute VOB path name:

    /vob-tag/pname-in-vob

  • Windows dynamic views—Absolute VOB path name:

    \vob-tag\pname-in-vob

  • UNIX and Linux dynamic views—View-extended path name:

    /view /view-tag/full-pathname

  • Windows dynamic views—View-extended path name:

    drive-letter:\view-tag\vob-tag\pname-in-vob

Description

This reference page describes ClearCase extensions to the standard file/directory namespace provided by the operating system. These extensions can be used as follows:

  • From a dynamic view, you can use the path name forms described here as arguments to any cleartool command that takes a path name.
  • From a snapshot view, you can use the VOB-extended path name forms as arguments to those cleartool commands that return information about elements and versions (for example, describe, ls, lshistory, and diff). Such operations do not require the MVFS. However, you cannot use VOB-extended path names forms to check out an element version that is not loaded into your view.
Note for Windows users: cleartool is case-sensitive. In cleartool subcommands, path names to MVFS objects, including view-private files in the MVFS namespace, must be case-correct. For information about restrictions on object names, see the cleartool reference page.

Dynamic view contexts

A path name can access ClearCase data only if it has a view context:

  • UNIX and Linux only: Set view context. A process, typically a shell, created with the setview command is said to have a set view context. That process, along with all of its children, is "set to the view."
  • Working directory view context. You can change the current working directory of a process to a view-extended path name:

    % cd /view/david/vobs/proj

    Such a process is said to have a working directory view context. (The process may or may not also have a set view context.)

  • View-extended path name. A path name can specify its own view context, regardless of the current (UNIX or Linux) set view or (UNIX, Linux, and Windows) working directory view contexts, if any.

Windows only: Dynamic view access model

All ClearCase data is accessed through the MVFS, which, by default, occupies drive M on each ClearCase host. The view tag of each active view appears in the root directory of drive M, and the VOB tag of each active VOB appears as a subdirectory under each active view.

From drive M, you can access VOBs by using view-specific path names of the form \view-tag\vob-tag\pname-in-vob. Typically, however, you do not work directly on drive M, but on a drive you have assigned to a view.

From any drive, you can specify view-extended path names of the form M:viewtag\vobtag\rest-of-path. If you move to drive M, you are in view-extended namespace, and all VOB access is by means of view-extended path names.

To eliminate any confusion that may result from unintentional use of view-extended path names, you must work from a drive letter assigned to a view. This practice permits you to use VOB path names of the form \myvob\vob-object-pname in both cleartool and standard operating system commands, from any view. Also, this approach is required if you want to share DOs between views at build time.

Kinds of path names

The following sections describe the kinds of path names you can use with ClearCase.

UNIX and Linux only: Standard path names

A standard path name is either full or relative:

  • A full path name begins with a slash (/):

    /usr/bin/cc

    The slash can be implied. For example:

    ~bertrand/proj/doc

    A full path name is interpreted in the process's set view context. An error occurs if you attempt to use a full path name to access ClearCase data in a process that is not set to a view.

  • A relative path name does not begin with a slash:

    foo.c
    ../motif/libX.a

A relative path name is interpreted in the process's working directory view context, if it has one. Otherwise, it uses the process's set view context. If a process has neither kind of view context, an error occurs.

A standard path name can reference any kind of file system object: For example, /vobs/proj/BAR references "file system object named BAR, as seen through the current view." This can be any of the following:

  • Version. If BAR names an element, the path name references the version of that element selected by the current view's config spec.
  • VOB symbolic link. BAR can name a VOB symbolic link that is visible in the current view. Depending on the command, the link may or may not be traversed.
  • Derived object. BAR can name a derived object that was built in the current view or was winked in to the view.
  • View-private object. BAR can name a view-private object (including a checked-out version) located in the current view's private storage area.
  • Non-MVFS object. BAR can name an object that is not under ClearCase control, such as objects in your home directory or in /usr/bin.

Using standard path names to reference MVFS objects is termed transparency: a view's view_server process resolves the standard path name into a reference to the appropriate MVFS object. In essence, transparency makes a VOB appear to be a standard directory tree.

Windows only: Standard path names

A standard path name is either full or relative:

  • A full path name begins with an optional drive letter and a backslash (drive-letter:\, or just \). The following full path names refer to the same VOB object, main.c, using view1. The element main.c resides in a VOB with VOB tag \vob3.

    M:\view1\vob3\src\main.c\view1\vob3\src\main.c

    Current drive is M

    Z:\vob3\src\main.c

    Z: assigned to M:\view1

    \vob3\src\main.c

    Current drive is Z

    Full path names to non-VOB objects:

    C:\users\anne\bin\myperl.exe

    View-private file: an MVFS object, but not in a VOB

    \users\anne

    Current drive is C

  • A relative path name does not begin with a backslash or with drive-letter:\:

    main.c
    ..\src\main.c
    Z:\main.c

A standard path name can reference any kind of file system object. Typically, you use the net use command or click Tools > Map Network Drive in Windows Explorer to set a working view (myview , for example), and then work from the drive assigned to M:\myview. In this case, a path name like \vob1\proj\bar references "file system object named bar, as seen through the current view." The referenced object can be any of the following:

  • Version. If BAR names an element, the path name references the version of that element selected by the current view's config spec.
  • VOB symbolic link. BAR can name a VOB symbolic link that is visible in the current view. Depending on the command, the link may or may not be traversed.
  • Derived object. BAR can name a derived object that was built in the current view or was winked in to the view.
  • View-private object. BAR can name a view-private object (including a checked-out version) located in the current view's private storage area.
  • Non-MVFS object. BAR can name an object that is not under ClearCase control, such as objects in your home directory or on other machines (for example, \\hyperion\c\misc\files.txt.

Using standard path names to reference MVFS objects is called transparency: a view's view_server process resolves the standard path name into a reference to the appropriate MVFS object. In essence, transparency makes a VOB appear to be a standard directory tree.

Note: Most ClearCase utilities, including cleartool, accept a slash (/) or backslash (\) as path name separators. That is, the following path names, when used as arguments to ClearCase programs, are equivalent:

Z:\myvob\src\test.h
Z:/myvob/src/text.h

Windows only: Absolute VOB path names

An absolute VOB path name is full path name that starts with a VOB tag.

Z:\myvob\src\main.c

Full path name to VOB object; drive Z assigned to some view

\myvob\src\main.c

Absolute VOB path name; begins with a VOB tag (\myvob)

Absolute VOB path names are valid only if the current drive is assigned to a view. (Manually attaching a drive letter to M:\view-tag with the subst command also enables absolute VOB path names.) This form of path name is commonly used in config specs (see config_spec), and it is also the form in which configurations records store references to MVFS objects.

Element pathnames in ACL-enabled VOBs

In a VOB with ACLs enabled, ClearCase enforces directory read permissions when constructing a pathname to an element. For example, if you display a UCM activity's change set, each version in the change set is displayed as a pathname that your account can use to access that version in the view context. All directories used in this pathname are readable to your account. If a version has no pathnames with all directories readable to your account, you will see a placeholder or substitute name (depending on the interface and operation involved). If the version itself is also unreadable to your account, you will see no details on the version.
Table 1. Unnameable element behavior
Interface Display of an unnameable version Display of unreadable version
cleartool (UCM activity) version unknown version unknown
cleartool (describe of element or version, such as by dbid) The displayed name of the object is the dbid, not a pathname error message (unable to resolve)
UNIX and Windows native GUIs (UCM activity's change set) Unavailable Unavailable
ClearTeam Explorer (UCM activity) Blank space in the Name column No details in any column
ClearQuest® web integration Unknown version Unknown version
rcleartool (UCM activity) Unknown version Unknown version

If you attempt to deliver or rebase a stream, and the operation requires a checkout/merge of an element that has no visible pathname, the operation fails. You can resume the operation once you fix the permission problem, or by using a different account that has access to all required elements.

Extended path names

The MVFS supports two kinds of extensions to the standard path name scheme:

  • You can add two path name components (UNIX or Linux) or a view tag prefix (Windows) to any MVFS object path name, turning it into a view-extended path name:

    /view/david/vobs/proj/foo.c

    View-extended full path name

    M:\dri_view\proj_vob\foo.c

    View-extended full path name

    \dri_view\proj_vob\foo.c

    View-extended full path name; M is the current drive

  • In certain situations, a relative path name can include a view specification:

    ../../david/vobs/proj/foo.c

    View-extended relative path name

    ..\..\dri_view\proj_vob\foo.c

    View-extended relative path name

  • You can add characters to the end of a relative or full path name, turning it into a VOB-extended path name. VOB-extended path names that specify versions of elements are the most commonly used; they are called version-extended path names.

    UNIX or Linux:

    foo.c@@/main/12

    Version-extended path name

    /vobs/proj/foo.c@@/main/motif/4

    Version-extended path name

    foo.c@@/RLS4.3

    Version-extended path name

    foo.c@@/main

    VOB-extended path name to a branch

    foo.c@@

    VOB-extended path name to an element

    hello.o@@2007-09-15T08:10.439

    VOB-extended path name to a derived object

    Windows:

    foo.c@@\main\12

    Version-extended path name

    \proj_vob\foo.c@@\main\bugfix\4

    Version-extended path name

    foo.c@@\RLS4.3

    Version-extended path name

    foo.c@@\main

    VOB-extended path name to a branch

    foo.c@@

    VOB-extended path name to an element

    hello.o@@2007-09-15T08:10.439

    VOB-extended path name to a derived object

View-extended path names

On UNIX and Linux systems, a view-extended path name is a standard path name, along with a specification of a view. For example, /view/david/vobs/proj/BAR references file system object named BAR, as seen through view david.A view-extended path name can access any kind of file system object, as described in UNIX and Linux only: Standard path names.

On Windows systems, a view-extended path name is a standard path name that references a VOB object or view-private object through a specific view. For example, M:\dri_view\proj_vob\BAR references file system object named BAR, as seen through view dri_view. A view-extended path name can access any kind of file system object, as described in UNIX and Linux only: Standard path names.

Note: Windows users generally perform ClearCase operations in a view, on a drive assigned to a view with the net use command. It is rare to work directly on drive M. It is common to use view-extended path names that include the M:\view-tag prefix. If you work directly on drive M, you are in view-extended namespace.

UNIX and Linux only: The viewroot directory/view tags

In most view-extended path names, a full path name is prefixed with two components: the name of the host's viewroot directory and the view tag of a particular view. The viewroot directory is a virtual data structure, whose contents exist only in MVFS buffers in main memory. Each view is made accessible to standard programs and ClearCase programs through a view tag entry in the viewroot directory. No standard command or program can modify this directory. Only a few ClearCase commands use or modify it: mkview, mktag, rmtag, rmview, startview.

The viewroot directory is activated by a standard mount(1M) command, which considers the virtual data structure to be a file system of type MVFS. The ClearCase path name of the viewroot directory is /view. For more information, see the init_ccase reference page and the DevOps Code ClearCase Administrator's Guide.

Windows only: The MVFS directory/view tags

Most view-extended path names are full path names that begin with the view tag of a particular view. Unless you are working explicitly on drive M, the view-extended path name also includes the M: prefix. Each view is made accessible to standard programs and ClearCase programs through a view tag entry on the dynamic-views drive, M. No standard command or program can modify the dynamic-views drive's root directory. Only a few ClearCase commands use or modify it: mkview, mktag, rmtag, rmview, and startview.

Symbolic links and the view-extended namespace

Path names are resolved component-by-component by the operating system kernel and the MVFS. When a UNIX or Linux symbolic link or VOB symbolic link is traversed, a full path name needs a UNIX or Linux set view context or a Windows view context to access ClearCase data. Thus, a symbolic link whose text is a full UNIX or Linux path name such as

/vobs/aardvark -> /vobs/all_projects/aardvark ...

or a Windows absolute VOB path name such as

\aardvark -> \all_projects\aardvark

is interpreted in the current UNIX or Linux set view context or Windows view context. If the process has no context, traversing such a symbolic link fails.

VOB-extended path names

The transparency feature enables you to use standard path names to access version-controlled data; the view_server does the work of locating the data. But you can also bypass transparency and do the work yourself:

  • You can access any version of an element by using its version ID, which specifies its exact version-tree location:

    sort.c@@/main/motif/4

  • If a version has been assigned a version label, you can access it using the label:

    sort.c@@\main\bugfix\RLS_1.3

    Branch and version label

    sort.c@@\RLS_1.3

    Version label only

    Typically, you can use the label, without having to specify the branch on which the labeled version resides; see Version labels in extended namespace.

  • You can access any element object or branch object directly:

    sort.c@@

    Element object

    sort.c@@/main

    Branch object

    sort.c@@/main/motif

    Branch object

  • You can access any derived object directly, regardless of the view it was created in:

    sort.o@@2007-08-13T09:45.569

    Derived object created on 13-Aug

    sort.o@@2007-09-23T19:09.743

    Derived object created on 23-Sep

The path names in these examples are called VOB-extended path names. A VOB's file/directory namespace is extended in two ways from the standard namespace: one extension enables direct access to elements, branches, and versions; the other enables direct access to derived objects. Both extensions allow you to access objects not visible in your own view (and perhaps not currently visible in any other view, either).

Extended namespace for elements, branches, and versions

An element's version tree has the same form as a standard directory tree.

Component of version tree

Component of directory tree in extended namespace

element

Root of tree: The element itself appears to be a directory, which contains a single subdirectory, corresponding to the main branch. (It can also contain some version label; see Version labels in extended namespace.)

branch

Subdirectory: Each branch appears to be a directory, which contains files (individual versions and version labels), directories (subbranches), and links (version labels).

version

Leaf name: Each version appears to be a leaf of a directory tree. For a file element, the leaf contains text lines or binary data. For a directory element, the leaf contains a directory structure.

Accordingly, any location within an element's version tree can be identified by a path name in this extended namespace:

sort.c@@

Specifies an element

sort.c@@/main

Specifies a branch

sort.c@@/main/branch1

Specifies a branch

sort.c@@/main/branch1/2

Specifies a version

doctn/.@@/main/3

Special case: extra component is required in VOB's top-level directory

Extended naming symbol

The previous path name examples incorporate the extended naming symbol (@@). This symbol is required to effect a switch from the standard file/directory namespace to the extended element/branch/version namespace. There are two equivalent ways to think of @@:

  • When appended to the name of any element, the extended naming symbol turns off transparency (automatic version-selection). Thus, you must specify one of the element's versions explicitly.
  • The extended naming symbol is part of an element's official name. For example, foo.c is the name of a version (the particular version that appears in the view); foo.c@@ is the name of the element itself.
Note: The establishment of @@ as the extended naming symbol occurs at system startup time with a file system table entry. Thus, different symbols may be used on different hosts. See the init_ccase reference page for details.

Version labels in extended namespace

Version labels appear in the extended namespace as hard links (UNIX and Linux) or as additional files (Windows).

On UNIX or Linux, if version /main/4 of an element is labeled RLS_1, the extended namespace directory corresponding to the element's main branch lists both 4 and RLS_1 as hard links to the version:

% ls -il sort.c@@/main
246 -r--r--r-- 1 drp user 217 2006-10-06T21:12 4
.
.
.
246 -r--r--r-- 1 drp user 217 2006-10-06T21:12 RLS_1

On Windows, if version \main\4 of an element is labeled RLS_1, the extended namespace directory corresponding to the element's main branch lists both 4 and RLS_1:

Z:\myvob\src> dir sort.c@@\main
2006-11-10T17:34                1846 4
 ...
2006-11-10T17:34                1846 RLS_1

If the label type was created with the once-per-element restriction, an additional UNIX or Linux hard link to the labeled version appears in the element's top-level directory:

% ls -il sort.c@@
246 -r--r--r-- 1 drp user 217 2006-10-06T21:12 RLS_1

On Windows, an entry for the labeled version appears in the element's top-level directory:

Z:\myvob\src> dir sort.c@@
2006-11-10T17:34                1846 RLS_1

In this case, all the following are equivalent extended path names to the labeled version:

UNIX or Linux:

sort.c@@/RLS_1

Version label at top level of element

sort.c@@/main/4

Version ID

sort.c@@/main/RLS_1

Version label at branch level

Windows:

sort.c@@\RLS_1

Version label at top level of element

sort.c@@\main\4

Version ID

sort.c@@\main\RLS_1

Version label at branch level

(The once-per-element restriction is the mklbtype default. A mklbtype –pbranch command creates a label type that can be used once on each branch of an element.)

Path names involving more than one element

A VOB can implement a deep directory structure. Thus, a path name can involve several elements. For example:

  • UNIX or Linux:

    /vobs/proj/src/include/sort.h

  • Windows:

    \proj_vob\src\include\sort.h

If proj or proj_vob is the VOB's root directory element, then src and include also name directory elements, and sort.h names a file element.

After a path name crosses over into the extended namespace with @@, you must specify a version for each succeeding element in the path name. For example:

  • UNIX or Linux:

    /vobs/proj/src/include@@/main/4/sort.h/main/LATEST

  • Windows:

    \proj_vob\src\include@@\main\4\sort.h\main\LATEST

To automatically select versions for elements proj and src: cross over to extended namespace at directory element include, specifying a version of include and a version of sort.h:

  • UNIX or Linux:

    /vobs/proj/src@@/RLS_1/include/RLS_1/sort.h/RLS_1

  • Windows:

    \proj_vob\src@@\RLS_1\include\RLS_1\sort.h\RLS_1

To automatically select versions for element proj only: cross over to extended namespace at directory element src, specifying the version labeled RLS_1 of each succeeding element:

  • UNIX or Linux:

    /vobs/proj@@/main/1/src/main/4

    Invalid

    /vobs/proj/.@@/main/1/src/main/4

    Valid

  • Windows:

    \proj_vob@@\main\1\src\main\4

    Invalid

    \proj_vob\.@@\main\1\src\main\4

    Valid

Note: When crossing over into extended namespace at the VOB root directory (that is, at the VOB tag or VOB mount point), you must use /.@@ or \.@@ instead of @@.

The extended naming symbol need be used only once in a path name, to indicate the crossover into extended namespace. You can, however, append it to any element name:

  • UNIX or Linux:

    /vobs/proj/src@@/RLS_1/include@@/RLS_1/sort.h@@/RLS_1

  • Windows:

    \proj_vob\src@@\RLS_1\include@@\RLS_1\sort.h@@\RLS_1

Reading and writing in the extended namespace

A VOB-extended path name references an object in a VOB database. The reference can either read or write the database, that is, either query metadata or modify metadata:

  • UNIX or Linux:

    % cleartool mklabel RLS2.1 util.c@@/RLS2.0

    Attach an additional label to a version

    % cleartool rmattr BugNum util.c@@/main/3

    Remove an attribute

  • Windows:

    Z:\myvob> cleartool mklabel RLS2.1 util.c@@\RLS2.0

    Attach an additional label to a version

    Z:\myvob> cleartool rmattr BugNum util.c@@\main\3

    Remove an attribute

For a version, an extended path name can also read the version's data, but cannot write or delete it:

  • UNIX or Linux:

    grep 'env' util.c@@/main/rel2_bugfix/1

    Valid

    rm util.c@@/main/rel2_bugfix/1

    Not valid

    ERROR: util.c@@/main/rel2_bugfix/1 not removed: Read-only file system.

  • Windows:

    Z:\myvob\src> find "env" util.c@@\main\rel2_bugfix\1

    Valid

    Z:\myvob\src> del util.c@@\main\rel2_bugfix\1

    Invalid

    Access is denied.

Extended namespace for derived objects

The extended namespace allows multiple derived objects to exist at the same standard path name. Multiple versions of an element also exist at the same standard path name, but the two extensions work differently. Derived objects created at the same location are distinguished by their unique derived object identifiers, or DO IDs:

sort.obj@@2006-09-14T09:54.418
sort.obj@@2006-09-13T09:30.404
sort.obj@@2006-09-02T16:23.353
.
.
.

An extended name provides access only to the derived object's metadata in the VOB database, principally, its configuration record. DO IDs can be used only with ClearCase commands; they cannot be used in non-ClearCase programs (for example, editors or compilers).

Navigating the VOB-extended namespace

You can use the operating system's directory-navigation commands in a VOB's extended namespace. For example, these are two equivalent ways to display the contents of an old version:

  • On UNIX or Linux:
    • Use a version-extended path name from a standard directory:

      % cat util.c@@/main/rel2_bugfix/1

    • Change to branch "directory" in the VOB-extended namespace, and then display the version:

      % cd util.c@@/main/rel2_bugfix
      % cat 1

  • On Windows:
    • Use a version-extended path name from a standard directory:

      Z:\myvob\src> type util.c@@\main\rel2_bugfix\1

    • Change to branch "directory" in the VOB-extended namespace, and then display the version:

      Z:\myvob\src> cd util.c@@\main\rel2_bugfix
      Z:\myvob\src> type 1

In VOB-extended namespace, elements and branches are directories; you can change to such directories with cd; you can lists their contents—branches and versions—with operating system commands.

You can access versions of file elements as ordinary files with operating system commands—even executing versions that happen to be compiled programs or scripts.

UNIX and Linux only: Special view tag reported by pwd. When you have changed to a VOB-extended namespace directory, the pwd(1) command reports your current working directory as under a special view tag: For example:

% cd /view/akp_vu/vobs/proj/special@@
% pwd
/view/akp_vu@@/vobs/proj/main/4/special

The special view tag akp_vu@@ appears as a separate entry from akp_vu in your host's viewroot directory. When in the context of a special view tag, version-selection is suppressed completely. To access a particular version of any file or directory element, you must specify the version explicitly. These special entries are periodically deleted on a least-recently-used basis.

UNIX and Linux only: Exiting from VOB-extended namespace. To exit VOB-extended namespace, change to a standard full path name or a view-extended path name. (The path name can specify a VOB or non-VOB location.) For example:

% cd /vobs/proj/src@@/main

Enter VOB-extended namespace

% pwd

/view/david@@/vobs/proj/main/ 4/src/main

/view/david@@/vobs/proj/main/4/src/main

% cd /vobs/proj

Exit VOB-extended namespace

pwd

/vobs/proj

Repeated use of cd .. does not work as you may expect. You do not exit extended namespace where you entered it; instead, you ascend through all the extended-namespace directories listed by pwd. For example:

% cd util.c@@/main/rel2_bugfix
% ls
0 1 2 LATEST
% pwd
/view/drp_fix@@/usr/hw/main/1/src/main/2/util.c/main/rel2_bugfix
% cd ../../..
% pwd
/view/drp_fix@@/usr/hw/main/1/src/main/2
% cd ../..
% pwd
/view/drp_fix@@/usr/hw/main/1/src
% cd ../../../
% pwd
/view/drp_fix@@/usr/hw

Windows only—Special "@@" view tags visible on drive M. When you activate a view, a subdirectory, view-tag, appears on drive M for that view. If you enter version-extended namespace while in that view, a parallel subdirectory, view-tag@@, also appears on drive M. For example:

C:\> net use f: \\view\myview
...
C:\> dir M:\
2006-11-15T22:24        <DIR>     myview

C:\> f:
F:\> cd \dev\lib@@
F:\dev\lib@@> dir M:
2006-11-15T22:24        <DIR>     myview
2006-11-15T22:24        <DIR>     myview@@