symlink(2)                 DG/UX 4.30                  symlink(2)



     NAME
          symlink - Create a symbolic link file.

     SYNOPSIS
          int   symlink  (link_contents, link_path)
          char *  link_contents;
          char *  link_path;

     PARAMETERS
          link_contents  Null terminated string to become the symbolic
                         link's contents.


          link_path      Address of a pathname.

     DESCRIPTION
          Symlink creates a symbolic link file named by the pathname
          pointed to by <link_path> that contains the null-terminated
          string pointed to by <link_contents>.

          <Link_contents> need not be a valid pathname in order to
          create the symbolic link.  When the symbolic link is
          resolved as part of a pathname, however, an error will occur
          if it does not obey all the pathname resolution rules.  The
          only validity test performed on <link_contents> is a check
          that no character has a high-order bit set.

          <Link_contents> must be less than MAXPATHLEN bytes long.
          This restriction is in addition to the size restrictions
          that apply to every file -- the process file size limit, and
          the system file size limit.

          The symbolic link file is entered into the filesystem.  The
          file's attributes are initialized as follows:

          *    The inode number (st_inod) refers to the per-file
               database allocated.

          *    The device number (st_dev) is the same as that of the
               directory containing the symbolic link file.  The
               represented device (st_rdev) is undefined.

          *    The number of links (st_nlink) is set to one.

          *    The file mode (st_mode) is set as follows:  The file
               type is `symbolic-link-file'.  The other mode fields
               are undefined.

          *    The user id (st_uid) is set to the effective user id of
               the calling process. (The user id is needed to support
               the protection required by readlink.) The group id
               (st_gid) is undefined.



     Licensed material--property of copyright holder(s)         Page 1

     symlink(2)                 DG/UX 4.30                  symlink(2)



          *    The file size (st_size) is set to the number of
               characters in <link_contents>, exclusive of the
               terminating null character.

          *    The time last accessed (st_atime), time last modified
               (st_mtime), and time of last attribute change
               (st_ctime) are set to the current time.

          <Link_path> is created in the containing directory and is
          made to identify the newly created file.  An allocation to
          the directory causes its attributes to change as follows:

          *    The file size (st_size) is updated.

          *    The time last modified (st_mtime) and time of last
               attribute change (st_ctime) are set to the current
               time.

          If symlink fails, no changes are made.

     ACCESS CONTROL
          The calling process must have permission to resolve
          <link_path>.

          The calling process must have write permission to the
          directory containing the symbolic link to be added.

     RETURN VALUE
          0              The symbolic link was successfully created.


          -1             An error occurred.  Errno is set to indicate
                         the error.

     EXCEPTIONS
          Errno may be set to one of the following error codes:


          EEXIST         The symbolic link named by <new_path> exists.


          EFAULT         <Link_contents> points outside the allocated
                         address space of the process.


          EPERM          The string pointed to by <link_contents>
                         contains a character with the high-order bit
                         set.


          EROFS          The requested symbolic link requires writing
                         in a directory on a file system mounted



     Licensed material--property of copyright holder(s)         Page 2

     symlink(2)                 DG/UX 4.30                  symlink(2)



                         read-only.


          ENOENT         The file the pathname resolved to does not
                         exist.


          ENOENT         A non-terminal component of the pathname does
                         not exist.


          ENOTDIR        A non-terminal component of the pathname was
                         not a directory or symbolic link.


          ENAMETOOLONG   The pathname exceeds the length limit for
                         pathnames.


          ENAMETOOLONG   A component of the pathname exceeds the
                         length limit for filenames.


          ENOMEM         There are not enough system resources to
                         resolve the pathname or to expand a symbolic
                         link.


          ELOOP          The number of symbolic links encountered
                         during pathname resolution exceeded
                         MAXSYMLINKS.  A symbolic link cycle is
                         suspected.


          EPERM          The pathname contains a character not in the
                         allowed character set.


          EFAULT         The pathname does not completely reside in
                         the process's address space or the pathname
                         does not terminate in the process's address
                         space.

     SEE ALSO
          The related manual sections:  ln(1),
          link(2), readlink(2), unlink(2),
          stat(5).








     Licensed material--property of copyright holder(s)         Page 3