TPF Symbolic Links

by Francis Gurtowski, IBM TPF Development

The good news is that on a personal computer (PC) you have probably already acquired enough familiarity with most of the file system concepts that you will ever need to understand in order to use the TPF file system productively. The concepts of file streams, directories, file names, and path names, for example, are essentially the same on DOS, OS/2, and TPF. Unless you missed completely the PC phenomenon, file systems are not "new news."

The bad news is that the file system concept of symbolic links is different. Nothing readily available on a PC can prepare you for symbolic links. Symbolic links require a UNIX workstation or UNIX server background. Although you may never actually encounter a TPF symbolic link, it would probably not be a waste of time for most TPF users to read this short description of symbolic links.

What are symbolic links?

Symbolic links are hybrid files:

• Part directory
• Part directory entry
• Part file stream.

On the surface, a symbolic link is like a directory in the sense that both may be used as path name components. You may use in path names the file names of symbolic links just as you may use the file names of directories there. In absolute path name /A/B/C, for example, path name components A, B, and C may be the file names of either directories or symbolic links. The same is true for path name components D, E, and F in relative path name D/E/F.

Below the surface, however, directories and symbolic links are quite different:

• Directories contain structured information, known as directory entries, while symbolic links contain file streams, which are only structured in the sense that they look like valid path names.

  The comparative contents of directories and symbolic links are pertinent to path name translation. Path name translation is the file system function that translates path names, one path name component at a time, from left to right, to the corresponding pointers to i-nodes. These i-node pointers reside in the directory entries, but not in the symbolic links.

  Each file has an i-node that tells the file system everything it needs to know about a file. The file system has to get to the appropriate i-node before it can even begin to access a file. That is where path name translation comes in. Its job is to get to the appropriate i-node.

  Depending on the composition of a particular path name, path name translation may have to search many directories, and even more directory entries, to find the pointer to the i-node of the final path name component. On the other hand, path name translation simply prepends the contents of symbolic links to the remaining path name components.

  That's right, symbolic links give path name translation more work to do. If each successfully searched directory yields one path name translation step forward (toward the goal of a pointer to the i-node of the final path name component), each successfully prepended symbolic link yields one or more path name translation steps back, away from that destination.

• Directories are characterized as "hard links" on a path name chain of links, while symbolic links are characterized as uot;soft links." Directories provide "hard" information in the sense of factual and real. The presence of a directory entry means the corresponding file does exist. Symbolic links provide "soft" information in the sense of speculative and unreal. The file named in a symbolic link may or may not actually exist.
• The path names resulting from prepending the contents of symbolic links to the remaining path name components may be either absolute path names or relative path names, but in the latter case, the resulting relative path names are not translated in the same way that ordinary relative path names are translated.

  Ordinary relative path names are translated relative to the current directory. Relative path names resulting from prepending the contents of a symbolic link are instead translated relative to the directory containing the directory entry for the symbolic link.

  Here is an example. Let us say that in the ordinary relative path name D/E/F, D is the file name of a directory and /D/E is the path name of a symbolic link containing the unordinary relative path name X/Y/Z. The first thing path name translation does is recall the pointer to the current directory. Path name translation keeps that i-node pointer around for translating ordinary relative path names (just like it keeps the i-node pointer to the root directory around for translating all absolute path names). Path name translation then searches the current directory for an entry for filename D. It finds that directory entry, gets the pointer to the i-node of the D file, and through that pointer discovers that D is a directory. Path name translation then searches the D directory for an entry for file name E. It finds that directory entry, gets the pointer to the i-node of the D/E file, and through that pointer discovers that D/E is a symbolic link. Path name translation then reads symbolic link D/E and prepends its contents, X/Y/Z, to the remaining path name components, F. The result is the unordinary relative path name X/Y/Z/F. Path name translation then searches the D directory again (not the current directory), this time for an entry for file name X, and proceeds accordingly.

  Now let us change this example slightly. Let us put an obvious flaw into the symbolic link. Let us change the contents of symbolic link D/E from X/Y/Z to just E. Then, when path name translation reads symbolic link D/E and prepends its contents to the remaining components, the result is the unordinary relative path name E/F. This flawed symbolic link causes an obvious loop in the D/E/F path name. Path name translation cannot get past directory D and file name E. Path name D/E/F can never be completely translated as long as file D/E is a symbolic link containing path name E.

  Other path name translation loops caused by flawed symbolic links are not so obvious. Path name translation guards against all such loops by limiting path names to no more than an arbitrary number of symbolic links. The limit is usually 8. Path name translation ends unsuccessfully when more than eight symbolic links are encountered (and sets errno to ELOOP).

• Path name translation handles the final path name component differently depending on whether it is the file name of a symbolic link or not and, if it is the file name of a symbolic link, depending on the file system application programming interface (API) requesting path name translation.

In the other case, path name translation may stop, too; or else it may continue translating the path name stored in the symbolic link. That is why you cannot access a symbolic link as a file with most of the TPF file system APIs. They continue path name translation when the final path name component is the file name of a symbolic link.

Only the TPF file system lstat() , readlink() , remove() , rename() , symlink() , and unlink() APIs stop path name translation when the final path name component is a symbolic link.

symlink() API.

The symlink() API takes two path name arguments: the name of the symbolic link and the value of the symbolic link. The

Now that you know what symbolic links are, here is what you can and cannot do with TPF symbolic links:

• Do you have a bunch of very long path names that are awkward to use?

  Store them in symbolic links with very short path names. Symbolic links are path name variables. You can use TPF symbolic links to provide very short aliases for very long path names.

• Do you have a bunch of Web pages with hard-to-maintain hyperlinks to a series of files that are periodically replaced?

  Store the current path name of the target file in a symbolic link, use the path name of the symbolic link in the hyperlinks, and then periodically update the single symbolic link rather than the many hyperlinks. You can use TPF symbolic links to create a single alias for a series of alternative files.

• Do you have a file with a bunch of hard links that is hard to remove because you are never sure that you have removed its final hard link?

  Change the aliases to symbolic links and then just remove its single hard link. You can use TPF symbolic links to create aliases for files that you need to be certain have been removed.

• Do you need an alias for a directory? (TPF and most UNIX systems prohibit the creation of alternative directory entries for dire ories. The other UNIX systems only allow the superuser to create alternative hard links to directories. These prohibitions or restrictions are enforced in order to avoid path name translation loops.)

  You can use TPF symbolic links to create aliases for directories as well as for other types of files.

• Do you need an alias for a file in another file system? (Certain UNIX systems support the notion of alternative file systems; an there the users or system operators sometimes want to create alternative directory entries in one file system for files in another file system. Directory entries cannot cross file system boundaries like that, however. On those UNIX systems, symbolic links are used instead to cross file system boundaries.)

Sorry, but neither TPF directory entries nor TPF symbolic links can be used to cross file system boundaries.