gtpc2m4hC/C++ Language Support User's Guide

link-Create a Link to a File

This function provides an alternative path name for an existing file and afterwards, the same file can be accessed using both path names. The link function creates a new link from the new path name to the file and the link may be in the same or a different directory.

Format

#include <unistd.h>
int link(const char *oldfile, const char *newname);

oldfile
The path name of the existing file.

newname
The path name to be created for the new link to the existing file.

This function provides an alternative path name for the existing file so that the file can be accessed by either the old or the new name. The link function creates a link from path name newname to an existing file with path name oldfile. The link can be stored in the same directory as the original file or in a completely different one.

Links are allowed to files only, not to directories.

This is a hard link, which ensures the existence of a file even after its original name has been removed.

If the link function successfully creates the link, it increments the link count of the file. The link count tells how many links there are to the file.

TPF deviation from POSIX

The TPF system does not support the atime (access time) or ctime (change time) time stamp.

If oldfile names a symbolic link, the link function creates a link that refers to the file that results from resolving the path name contained in the symbolic link. If newname names a symbolic link, the link function fails and sets errno to EEXIST.

Normal Return

If successful, the link function returns a value of 0.

Error Return

If unsuccessful, the link function returns a value of -1 and sets errno to one of the following:

EACCES
The process does not have appropriate permissions to create the link. Possible reasons include no search permission on a path name component of oldfile or newname, no write permission on the directory intended to contain the link.

EEXIST
Either newname refers to a symbolic link, or a file or directory with the name newname already exists.

EINVAL
Either oldfile or newname is incorrect.

ELOOP
A loop exists in symbolic links. This error is issued if the number of symbolic links found while resolving the oldfile or newname argument is greater than the POSIX_SYMLOOP.

ENAMETOOLONG
oldfile or newname is longer than the PATH_MAX value, or a component of one of the path names is longer than the NAME_MAX value. For symbolic links, the length of the path name string substituted for a symbolic link in oldfile or newname exceeds the PATH_MAX value.

ENOENT
A path name component of oldfile or newname does not exist, oldfile itself does not exist, or one of the two arguments is an empty string.

ENOSPC
The directory intended to contain the link cannot be extended to contain another entry.

ENOTDIR
A path name component of one of the arguments is not a directory.

EPERM
oldfile is the name of a directory and links to directories are not supported.

Programming Considerations

 The TPF system does not support creating, updating, or deleting files in 1052 or UTIL state. Special files may or may not be writable in 1052 or UTIL state depending on the device driver implementation. 

Because the link function requires an update to a directory file, new links cannot be created in 1052 or UTIL state.

Examples

The following example provides link information for a file.

#include <fcntl.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
 
main() {
  char fn[]="link.example.file";
  char ln[]="link.example.link";
  int fd;
 
  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(fd);
    if (link(fn, ln) != 0) {
      perror("link() error");
      unlink(fn);
    }
    else {
      unlink(fn);
      unlink(ln);
    }
  }
}

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.