ln

Creates VOB hard link or VOB symbolic link.

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • VersionVault--Create one link:
    ln [ –s/link [ –rep/lace ] ] [–c/omment comment | –cfi/le comment-file-pname
    |–cq/uery | –cqe/ach | –nc/omment ]

    [ –nco [ –f/orce ] ] pname target-pname

  • VersionVault--Create one or more links in a specified directory:
    ln [ –s/link ] [ –c/omment comment | –cfi/le comment-file-pname
    |–cq/uery | –cqe/ach | –nc/omment ]

    [ –nco [ –f/orce ] ] pname [ pname ... ] target-dir-pname

  • VersionVault Remote Client--Create one link:
    ln [ –s/link [ –rep/lace ] ] [–c/omment comment
    |–cq/uery | –cqe/ach | –nc/omment ]

    pname target-pname

  • VersionVault Remote Client--Create one or more links in a specified directory:
    ln [ –s/link ] [ –c/omment comment
    |–cq/uery | –cqe/ach | –nc/omment ]

    pname [ pname ... ] target-dir-pname

Description

The links created with the ln command (VOB symbolic links or VOB hard links) are cataloged in directory versions, in the same way as elements. By default, a link can be created in a directory only if that directory is checked out. A VOB link becomes visible to those using other views only after you have checked in the directory in which you created the link. (ln appends an appropriate default checkin comment to the directory version.)

If evil twin detection is enabled and the creation of a hard or soft link would result in an evil twin of an existing element, an error is returned and the link is not created.

In a snapshot view, this command executes the update command for elements affected by the link operation.

VOB symbolic links

A VOB symbolic link (created when you use the –slink option) is a separate, unversioned object. It contains a character string, the link text, in the form of a path name. You can attach attributes and hyperlinks, but not version labels, to a VOB symbolic link.

You cannot check out a VOB symbolic link. To revise a VOB symbolic link, check out its directory, remove the link with rmname, create a new link, and check in the directory. (If you use the –nco option, the checkout and checkin steps are not required.)

VOB symbolic links in UNIX and Linux

Use relative VOB symbolic links instead of absolute VOB symbolic links. Absolute VOB symbolic links require you to use absolute path names from the VOB tag level; if the VOB mount point should change, the link becomes invalid.

VOB symbolic links in Windows

VOB symbolic links that point to files outside the VersionVault MVFS are not supported by the Windows operating system. Although the ln command creates the link, the link is not displayed in a standard directory listing; it is displayed only by the cleartool ls command. (This is true for all symbolic links that do not point to a valid MVFS path name.)

Use relative VOB symbolic links instead of absolute VOB symbolic links. Absolute VOB symbolic links require you to use absolute path names from the view tag level and are therefore valid only in the view in which they were created.

Note: Although an absolute VOB symbolic link that includes the view tag at the beginning works when you are in the view, an absolute VOB symbolic link pointing to a path name that begins with a VOB tag (for example, cleartool ln \my_vob\file my_link) does not work.

VOB hard links

A VOB hard link (created if you omit the –slink option) is an additional name for an existing element. Use VOB symbolic links instead of VOB hard links whenever possible.

VOB hard links in UNIX and Linux

In UNIX and Linux, you cannot make a VOB hard link to a derived object, but you can make additional UNIX and Linux system hard links (created with ln(1)) to a derived object. The links are visible in your view, but are not part of the VOB. For more information, see the VersionVault Guide to Building Software.

VOB hard links in Windows

When you check out a VOB hard link (that is, check out the element it names), all the other names for the element are listed by (cleartool) ls as checkedout but removed and are not displayed in Windows Explorer. The element is checked out, but there are no view-private files having the other names. The command lscheckout –all lists the checked-out element only once.

After you check in the element or cancel the checkout (using uncheckout), the other names for the element are listed by (cleartool) ls as disputed checkout, checkedout but removed and do not appear in Windows Explorer. To update the state of the other names, use the setcs –current command.

VOB hard links and directory merges

The merge and findmerge commands can merge both file elements and directory elements. Merging versions of a directory element can involve creating a VOB hard link to a directory or removing a VOB hard link from a directory:

  • Working on a subbranch, a user checks out the directory /src, and then either uses mkdir to create directory element /testing within /src or uses rmname to remove /testing from /src.
  • When the subbranch is merged back into the main branch, a hard link named testing is made in (or removed from) a main-branch version of src, referencing the directory element already cataloged in the subbranch version.

VersionVault allows creation of hard links to directories only in this directory-merge context: the two links (both named testing in the example above) must occur in versions of the same directory element (/src in the example above).

VOB hard links in snapshot views

In a snapshot view, a VOB hard link is a copy of the element to which it points.

Recovering a removed element

You can use ln to recover an element that you mistakenly removed from a VOB directory with rmname. For details, see the rmname reference page. You cannot use ln to link elements that are in the lost+found directory.

Restrictions

Identities

No special identity is required if you checked out the directory. To use the –nco option, you must have one of the following identities:

  • VOB owner
  • root (UNIX and Linux)
  • Member of the VersionVault administrators group (VersionVault on Windows)

Locks

An error occurs if one or more of these objects are locked: VOB.

Mastership

(Replicated VOBs only) No mastership restrictions.

Other

If you have multiple components in a UCM VOB, ln cannot be used to create hard links between these components.

Options and arguments

Type of link

Default
VOB hard links.
–s/link
Creates VOB symbolic links.

Event records and comments

Default
Creates one or more event records, with commenting controlled by your .versionvault_profile file (default: –nc). See the comments reference page. Comments can be edited with chevent.
–c/omment comment | –cfi/le comment-file-pname |–cq/uery | –cqe/ach | –nc/omment
Overrides the default with the option you specify. See the comments reference page.

Creating a link in a checked-in directory version

Default
None. You must check out a directory to create a link in it.
–nco [ –f/orce ]
Prompts for confirmation, then creates the link in the checked-in directory version that you specify. Use the –force option to suppress the confirmation prompt.
Note: You cannot use –nco in a replicated VOB.

Specifying the element to which the link points

Default
None.
pname ...
Specifies an element to which a link is to be created. Each pname must be a standard or view-extended path name. Use slashes (/) as path name separators if you need to load the symlinks from UNIX, Linux, and Windows. For VOB hard links, each pname must specify an existing element that is not a VOB symbolic link and that resides in the same VOB as the link being created. For VOB symbolic links, pname need not reside in the same VOB as the link to it, nor be an existing element.

Specifying the name of the link

Default
None.
target-pname
A path name that specifies the name for the VOB link to pname. An error occurs if an object already exists at target-pname. For a VOB hard link, pname and target-pname must reside in the same VOB; this restriction does not apply to VOB symbolic links.
target-dir-pname
The path name of an existing directory element in the same VOB as the pname argument. ln creates a new link in this directory for each preceding pname argument.
Note: This form of the command is intended for the creation of VOB hard links. If you use this form to create VOB symbolic links, make sure the links do not point to themselves. For example, the following command creates circular links:

cleartool ln –s file.txt dir1
Link created: "dir1/file.txt".
cd dir1
ls –l
lrwxrwxrwx  1 smg  user   8  2007-05-12T13:36 file.txt -> file.txt

The following command creates symbolic links that are not circular:

cleartool ln –s ../file.txt .
Link created: "./file.txt".
cd dir1 ls –l
lrwxrwxrwx  1 smg  user   8  2007-05-12T13:36 file.txt -> ../file.txt

Replacing the target of an existing symbolic link

Default
A new symbolic link is created.
–rep/lace
If the target-pname parameter exists as a symbolic link, this option replaces the current target text with pname.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you might need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Create a VOB hard link, hw.c, as another name for element hello.c.

    cmd-context ln hello.c hw.c
    Link created: "hw.c".

  • Create a VOB symbolic link, messages.c, pointing to msg.c.

    cmd-context ln -slink msg.c messages.c
     Link created: "messages.c".

  • Create a group of hard links in the subd directory for all .h files in the current working directory.

    cmd-context ln *.h subd
    Link created: "subd/hello.h".
    Link created: "subd/msg.h".
    Link created: "subd/util.h".

  • On a Windows system, as a member of the VersionVault administrators group (VersionVault), create a VOB symbolic link in the checked-in directory version \vobs_hw@@\main\3 that points to hello.c in the current working directory.

    cmd-context ln -slink -nco hello.c ..\vobs_hw@@\main\3\hello.c
    Modify checked-in directory version “\vobs_hw@@\main\3�?? [no]
    yes
    Link created: “..\vobs_hw@@\main\3\hello.c�?.