gtpc2m73C/C++ Language Support User's Guide

symlink-Create a Symbolic Link to a Path Name

This function creates a symbolic link to a path name.

Format

#include <unistd.h>
int symlink(const char *pathname, const char *slink);

pathname
A pointer to the path name to which the symbolic link resolves.

slink
The name of the symbolic link.

This function creates the symbolic link named by slink with the file specified by pathname. File access checking is not performed on the pathname file and the file does not need to exist.

A symbolic link path name is resolved as follows:

Because the mode of a symbolic link cannot be changed, its mode is ignored during the lookup process. Any files and directories to which a symbolic link refers are checked for access permission.

Normal Return

If successful, the symlink function returns a value of zero.

Error Return

If unsuccessful, the symlink function returns a value of -1, does not affect any file it names, and sets errno to one of the following:

EACCES
A component of the slink path prefix denies search permission, or write permission is denied in the parent directory of the symbolic link to be created.

EINVAL
This may be returned for the following reason:

ENAMETOOLONG
pathname is longer than PATH_MAX characters or some component of pathname is longer than NAME_MAX characters. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX.

ENOTDIR
A component of the path prefix of slink is not a directory.

ELOOP
A loop exists in symbolic links. This error is issued if the number of symbolic links found while resolving the slink argument is greater thatn POSIX_SYMLOOP.

EEXIST
The file named by slink already exists.

ENOSPC
The new symbolic link cannot be created because there is no space left on the file system that will contain the symbolic link.

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 symlink function requires an update to a directory file, new symbolic links cannot be created in 1052 or UTIL state.

Examples

The following example provides symlink 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[]="test.file";
  char sln[]="test.symlink";
  int fd;
 
  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(fd);
    if (symlink(fn, sln) != 0) {
      perror("symlink() error");
      unlink(fn);
    }
    else {
      unlink(fn);
      unlink(sln);
    }
  }
}

Related Information

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