link()--Create Link to File

 #include <unistd.h>

 int link(const char *existing, const char *new);  

The link() function provides an alternative path name for the existing file, so that the file can be accessed by either the existing name or the new name. link() creates a link with a path name new to an existing file whose path name is existing. The link can be stored in the same directory as the original file or in a different directory.

The link() function creates a hard link, which guarantees the existence of a file even after the original path name has been removed.

If link() successfully creates the link, it increments the link count of the file. The link count indicates how many links there are to the file. If link() fails for some reason, the link count is not incremented.

If the existing argument names a symbolic link, link() creates a link that refers to the file that results from resolving the path name contained in the symbolic link. If new names a symbolic link, link() fails and sets errno to [EEXIST].

A successful link updates the change time of the file, and the change time and modification time of the directory that contains new (parent directory).

If the file is checked out by another user (a user profile other than the user profile of the current job), link() fails with the [EBUSY] error.

Links created by this function are not allowed to cross file systems. For example, you cannot create a link to a file in the QOpenSys directory from the "root" (/) directory.

Links are not allowed to directories. If existing names a directory, link() fails and sets errno to [EPERM].

A job must have access to a file to link to it.

Parameters

existing

(Input) A pointer to a null-terminated path name naming an existing file to which a new link is to be created.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgLink()--Create Link to File for a description and an example of supplying the existing in any CCSID.

new

(Input) A pointer to a null-terminated path name that is the name of the new link.

This parameter is assumed to be represented in the CCSID currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job. The new link name is assumed to be represented in the language and country or region currently in effect for the job.

See QlgLink()--Create Link to File for a description and an example of supplying the new in any CCSID.

Authorities

Note: Adopted authority is not used.

Authorization Required for link()

Return Value

0

link() was successful.

-1

link() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If link() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. The link() function should be used sparingly to avoid potential performance degradation. The greater the number of hard links to an object, the more time it will take to change the attributes of the object.
   
   
3. The following file systems do not support link():
   • QSYS.LIB
   • Independent ASP QSYS.LIB
   • QDLS
   • QOPT
   • QFileSvr.400
   • QNetWare
   • QNTC

   If link() is used in any of these file systems, a [ENOSYS] error is returned.

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
  
• QlgLink()--Create Link to File
  
• rename()--Rename File or Directory
  
• unlink()--Remove Link to File

Example

See Code disclaimer information for information pertaining to code examples.

The following example uses link():

#include <stdio.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <stdlib.h>


main()
{
  char fn[]="link.example.file";
  char ln[]="link.example.link";
  int file_descriptor;
  struct stat info;

  if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(file_descriptor);
    puts("before link()");
    stat(fn,&info);
    printf("   number of links is %hu\n",info.st_nlink);
    if (link(fn, ln) != 0) {
      perror("link() error");
      unlink(fn);
    }
    else {
      puts("after link()");
      stat(fn,&info);
      printf("   number of links is %hu\n",info.st_nlink);
      unlink(ln);
      puts("after first unlink()");
      stat(fn,&info);
      printf("   number of links is %hu\n",info.st_nlink);
      unlink(fn);
    }
  }
}

Output:

before link()
   number of links is 1
after link()
   number of links is 2
after first unlink()
   number of links is 1