readlink()--Read Value of Symbolic Link

 #include <unistd.h>

 int readlink(const char *path, char *buf, size_t bufsiz);  

The readlink() function places the contents of the symbolic link path in the buffer buf. The size of the buffer is set by bufsiz. The contents of the returned buffer do not include a terminating NULL. When bufsiz is 0, the number of bytes contained in the symbolic link is returned and the buffer is unchanged.

If the buffer is too small to contain the contents of the symbolic link, the contents are truncated to the size of the buffer (bufsiz).

A successful readlink(), where bufsiz is greater than zero, sets the access time of the symbolic link.

Parameters

path

(Input) A pointer to the null-terminated path name of the symbolic link.

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 QlgReadlink()--Read Value of Symbolic Link for a description and an example of supplying the path in any CCSID.

buf

(Output) A pointer to the area in which the contents of the link should be stored.

This parameter will be returned 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.

See QlgReadlink()--Read Value of Symbolic Link for a description and an example of how to retrieve the symbolic link contents in any CCSID.

bufsiz

(Input) The size of buf in bytes.

Authorities

Note: Adopted authority is not used.

Return Value

value

readlink() was successful.

For the readlink() API, when bufsiz is greater than zero, the value returned is the number of bytes placed in the buffer. When bufsiz is zero, the value returned is the number of bytes contained in the symbolic link, and the buffer is not changed.

For the QlgReadlink API, when bufsiz is greater than the size of a Qlg_Path_Name_T structure, the value returned is the number of bytes of symbolic link contents placed in buf. This value does not include the size of the Qlg_Path_Name_T structure itself. When bufsiz is less than or equal to the size of a Qlg_Path_Name_T structure, the value returned is the number of bytes contained in the symbolic link, and the buffer is not changed.

If the return value is equal to bufsiz, the entire contents of the symbolic link may not have been returned. You can determine the size of the contents of the symbolic link by using either lstat() or readlink() with a zero value for bufsiz.

-1

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

Error Conditions

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

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

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
     • Network File System
     • QFileSvr.400
     
     
   
   
2. The following file systems do not support readlink().
   • QSYS.LIB
   • Independent ASP QSYS.LIB
   • QDLS
   • QOPT
   • QNTC

Related Information

• The <unistd.h> file (see Header Files for UNIX^®-Type Functions)
• lstat()--Get File or Link Information
• QlgReadlink()--Read Value of Symbolic Link
• stat()--Get File Information
• symlink()--Make Symbolic Link
• unlink()--Remove Link to File

Example

The following example uses readlink().

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

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

main() {
  char fn[]="readlink.file";
  char sl[]="readlink.symlink";
  char buf[30];
  int  file_descriptor;

  if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(file_descriptor);
    if (symlink(fn, sl) != 0)
      perror("symlink() error");
    else {
      if (readlink(sl, buf, sizeof(buf)) < 0)
        perror("readlink() error");
      else printf("readlink() returned '%s' for '%s'\n", buf, sl);

      unlink(sl);
    }
    unlink(fn);
  }
}

Output:

readlink() returned 'readlink.file' for 'readlink.symlink'

[ Back to top | UNIX-Type APIs | APIs by category ]