ln

Creates VOB hard link or VOB symbolic link

APPLICABILITY

ClearCase (cleartool subcommand), Attache (command)

SYNOPSIS

• Create one link:

  ln [ -s·link ] [-c·omment comment | -cfi·le comment-file-pname |-cq·uery

  
  

  | -cqe·ach | -nc·omment ]
  [ -nco [ -f·orce ] ] pname link-pname

• 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

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 when you check in the directory in which you create the link. (ln appends an appropriate line to the directory's checkout comment. The line is also the default checkin comment.)

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 if you use the -slink option) is a separate, unversioned object. It contains a character string, the link text, in the form of a pathname. 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. (Note that if you use the -nco option, the checkout and checkin steps are not required.)

Symbolic links that point to files outside the ClearCase MVFS are not supported by the Windows operating system. Although the ln command creates the link, the link does not appear 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 pathname.)

We recommend that you use relative VOB symbolic links instead of absolute symbolic links. Absolute VOB symbolic links require you to use absolute pathnames from the view-tag level (for example, \view-tag\VOB-tag\filename), and therefore are valid only in the view in which they were created.

NOTE: Although an absolute symbolic link that includes the view-tag at the beginning works when you are in the view, an absolute symbolic link pointing to a pathname 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. We recommend that you use VOB symbolic links instead of VOB hard links whenever possible.

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 a ClearCase or Attache ls command as checkedout but removed and does not appear in Windows Explorer. The element is checked out, but there are no view-private files with 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 a ClearCase or Attache ls command as disputed checkout, checkedout but removed and will not appear in Windows Explorer. To update the state of the other names, use the setcs -current command.

You cannot make a VOB hard link to a derived object.

VOB Hard Links and Directory Merges

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

• Working on a subbranch, a user checks out directory src, and then uses mkdir to create directory element testing within src or uses rmname to remove testing from the src directory.
• 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.

ClearCase and Attache allow 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 its target.

RECOVERING A REMOVED ELEMENT

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

PERMISSIONS AND LOCKS

Permissions Checking: No special permissions required if you checked out the directory. You must be VOB owner or a member of the ClearCase group to use the -nco option. See the permissions reference page.

Locks: An error occurs if the VOB is locked.

OPTIONS AND ARGUMENTS

TYPE OF LINK.  Default: Creates one or more 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 .clearcase_profile file (default: -nc). See CUSTOMIZING COMMENT HANDLING in 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: 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 LINK TARGET.  Default: None.

pname ...

Specifies an existing element; each pname must be a standard or view-extended pathname. For VOB hard links, each pname must specify an existing element (it cannot be a VOB symbolic link) in the same VOB as the link being created.

SPECIFYING THE NAME OF THE NEW LINK.  Default: None.

link-pname

A pathname within the same VOB as pname, at which one new VOB hard link or VOB symbolic link is to be created. An error occurs if an object already exists at link-pname.

target-dir-pname

The pathname 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 hard links. If you use this form to create 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

cleartool ls
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

cleartool ls
file.txt -> ..\file.txt

EXAMPLES

Examples including wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may 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 command interpreter prompt. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace 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".

• As a member of the ClearCase group, 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".

SEE ALSO

describe, mv, rename, update