diff options
Diffstat (limited to 'bin/ln')
| -rw-r--r-- | bin/ln/Makefile | 13 | ||||
| -rw-r--r-- | bin/ln/Makefile.depend | 15 | ||||
| -rw-r--r-- | bin/ln/ln.1 | 319 | ||||
| -rw-r--r-- | bin/ln/ln.c | 378 | ||||
| -rw-r--r-- | bin/ln/symlink.7 | 481 | ||||
| -rw-r--r-- | bin/ln/tests/Makefile | 3 | ||||
| -rw-r--r-- | bin/ln/tests/Makefile.depend | 10 | ||||
| -rw-r--r-- | bin/ln/tests/ln_test.sh | 295 |
8 files changed, 1514 insertions, 0 deletions
diff --git a/bin/ln/Makefile b/bin/ln/Makefile new file mode 100644 index 000000000000..0220ac3ba459 --- /dev/null +++ b/bin/ln/Makefile @@ -0,0 +1,13 @@ +.include <src.opts.mk> + +PACKAGE=runtime +PROG= ln +MAN= ln.1 symlink.7 + +LINKS= ${BINDIR}/ln ${BINDIR}/link +MLINKS= ln.1 link.1 + +HAS_TESTS= +SUBDIR.${MK_TESTS}+= tests + +.include <bsd.prog.mk> diff --git a/bin/ln/Makefile.depend b/bin/ln/Makefile.depend new file mode 100644 index 000000000000..6ef78fac5cbf --- /dev/null +++ b/bin/ln/Makefile.depend @@ -0,0 +1,15 @@ +# Autogenerated - do NOT edit! + +DIRDEPS = \ + include \ + include/xlocale \ + lib/${CSU_DIR} \ + lib/libc \ + lib/libcompiler_rt \ + + +.include <dirdeps.mk> + +.if ${DEP_RELDIR} == ${_DEP_RELDIR} +# local dependencies - needed for -jN in clean tree +.endif diff --git a/bin/ln/ln.1 b/bin/ln/ln.1 new file mode 100644 index 000000000000..43522e0c1cb8 --- /dev/null +++ b/bin/ln/ln.1 @@ -0,0 +1,319 @@ +.\"- +.\" Copyright (c) 1980, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the Institute of Electrical and Electronics Engineers, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd June 12, 2017 +.Dt LN 1 +.Os +.Sh NAME +.Nm ln , +.Nm link +.Nd link files +.Sh SYNOPSIS +.Nm +.Op Fl L | Fl P | Fl s Op Fl F +.Op Fl f | iw +.Op Fl hnv +.Ar source_file +.Op Ar target_file +.Nm +.Op Fl L | Fl P | Fl s Op Fl F +.Op Fl f | iw +.Op Fl hnv +.Ar source_file ... +.Ar target_dir +.Nm link +.Ar source_file Ar target_file +.Sh DESCRIPTION +The +.Nm +utility creates a new directory entry (linked file) for the file name +specified by +.Ar target_file . +The +.Ar target_file +will be created with the same file modes as the +.Ar source_file . +It is useful for maintaining multiple copies of a file in many places +at once without using up storage for the +.Dq copies ; +instead, a link +.Dq points +to the original copy. +There are two types of links; hard links and symbolic links. +How a link +.Dq points +to a file is one of the differences between a hard and symbolic link. +.Pp +The options are as follows: +.Bl -tag -width flag +.It Fl F +If the target file already exists and is a directory, then remove it +so that the link may occur. +The +.Fl F +option should be used with either +.Fl f +or +.Fl i +options. +If neither +.Fl f +nor +.Fl i +is specified, +.Fl f +is implied. +The +.Fl F +option is a no-op unless +.Fl s +is specified. +.It Fl L +When creating a hard link to a symbolic link, +create a hard link to the target of the symbolic link. +This is the default. +This option cancels the +.Fl P +option. +.It Fl P +When creating a hard link to a symbolic link, +create a hard link to the symbolic link itself. +This option cancels the +.Fl L +option. +.It Fl f +If the target file already exists, +then unlink it so that the link may occur. +(The +.Fl f +option overrides any previous +.Fl i +and +.Fl w +options.) +.It Fl h +If the +.Ar target_file +or +.Ar target_dir +is a symbolic link, do not follow it. +This is most useful with the +.Fl f +option, to replace a symlink which may point to a directory. +.It Fl i +Cause +.Nm +to write a prompt to standard error if the target file exists. +If the response from the standard input begins with the character +.Sq Li y +or +.Sq Li Y , +then unlink the target file so that the link may occur. +Otherwise, do not attempt the link. +(The +.Fl i +option overrides any previous +.Fl f +options.) +.It Fl n +Same as +.Fl h , +for compatibility with other +.Nm +implementations. +.It Fl s +Create a symbolic link. +.It Fl v +Cause +.Nm +to be verbose, showing files as they are processed. +.It Fl w +Warn if the source of a symbolic link does not currently exist. +.El +.Pp +By default, +.Nm +makes +.Em hard +links. +A hard link to a file is indistinguishable from the original directory entry; +any changes to a file are effectively independent of the name used to reference +the file. +Directories may not be hardlinked, and hard links may not span file systems. +.Pp +A symbolic link contains the name of the file to +which it is linked. +The referenced file is used when an +.Xr open 2 +operation is performed on the link. +A +.Xr stat 2 +on a symbolic link will return the linked-to file; an +.Xr lstat 2 +must be done to obtain information about the link. +The +.Xr readlink 2 +call may be used to read the contents of a symbolic link. +Symbolic links may span file systems and may refer to directories. +.Pp +Given one or two arguments, +.Nm +creates a link to an existing file +.Ar source_file . +If +.Ar target_file +is given, the link has that name; +.Ar target_file +may also be a directory in which to place the link; +otherwise it is placed in the current directory. +If only the directory is specified, the link will be made +to the last component of +.Ar source_file . +.Pp +Given more than two arguments, +.Nm +makes links in +.Ar target_dir +to all the named source files. +The links made will have the same name as the files being linked to. +.Pp +When the utility is called as +.Nm link , +exactly two arguments must be supplied, +neither of which may specify a directory. +No options may be supplied in this simple mode of operation, +which performs a +.Xr link 2 +operation using the two passed arguments. +.Sh EXAMPLES +Create a symbolic link named +.Pa /home/src +and point it to +.Pa /usr/src : +.Pp +.Dl # ln -s /usr/src /home/src +.Pp +Hard link +.Pa /usr/local/bin/fooprog +to file +.Pa /usr/local/bin/fooprog-1.0 : +.Pp +.Dl # ln /usr/local/bin/fooprog-1.0 /usr/local/bin/fooprog +.Pp +As an exercise, try the following commands: +.Bd -literal -offset indent +# ls -i /bin/[ +11553 /bin/[ +# ls -i /bin/test +11553 /bin/test +.Ed +.Pp +Note that both files have the same inode; that is, +.Pa /bin/[ +is essentially an alias for the +.Xr test 1 +command. +This hard link exists so +.Xr test 1 +may be invoked from shell scripts, for example, using the +.Li "if [ ]" +construct. +.Pp +In the next example, the second call to +.Nm +removes the original +.Pa foo +and creates a replacement pointing to +.Pa baz : +.Bd -literal -offset indent +# mkdir bar baz +# ln -s bar foo +# ln -shf baz foo +.Ed +.Pp +Without the +.Fl h +option, this would instead leave +.Pa foo +pointing to +.Pa bar +and inside +.Pa foo +create a new symlink +.Pa baz +pointing to itself. +This results from directory-walking. +.Pp +An easy rule to remember is that the argument order for +.Nm +is the same as for +.Xr cp 1 : +The first argument needs to exist, the second one is created. +.Sh COMPATIBILITY +The +.Fl h , +.Fl i , +.Fl n , +.Fl v +and +.Fl w +options are non-standard and their use in scripts is not recommended. +They are provided solely for compatibility with other +.Nm +implementations. +.Pp +The +.Fl F +option is a +.Fx +extension and should not be used in portable scripts. +.Sh SEE ALSO +.Xr link 2 , +.Xr lstat 2 , +.Xr readlink 2 , +.Xr stat 2 , +.Xr symlink 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Nm +utility conforms to +.St -p1003.2-92 . +.Pp +The simplified +.Nm link +command conforms to +.St -susv2 . +.Sh HISTORY +An +.Nm +command appeared in +.At v1 . diff --git a/bin/ln/ln.c b/bin/ln/ln.c new file mode 100644 index 000000000000..3055c7563cca --- /dev/null +++ b/bin/ln/ln.c @@ -0,0 +1,378 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1987, 1993, 1994 + * The Regents of the University of California. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/param.h> +#include <sys/stat.h> + +#include <err.h> +#include <errno.h> +#include <fcntl.h> +#include <libgen.h> +#include <limits.h> +#include <stdbool.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <unistd.h> + +static bool fflag; /* Unlink existing files. */ +static bool Fflag; /* Remove empty directories also. */ +static bool hflag; /* Check new name for symlink first. */ +static bool iflag; /* Interactive mode. */ +static bool Pflag; /* Create hard links to symlinks. */ +static bool sflag; /* Symbolic, not hard, link. */ +static bool vflag; /* Verbose output. */ +static bool wflag; /* Warn if symlink target does not + * exist, and -f is not enabled. */ +static char linkch; + +static int linkit(const char *, const char *, bool); +static void link_usage(void) __dead2; +static void usage(void) __dead2; + +int +main(int argc, char *argv[]) +{ + struct stat sb; + char *targetdir; + int ch, exitval; + + /* + * Test for the special case where the utility is called as + * "link", for which the functionality provided is greatly + * simplified. + */ + if (strcmp(getprogname(), "link") == 0) { + while (getopt(argc, argv, "") != -1) + link_usage(); + argc -= optind; + argv += optind; + if (argc != 2) + link_usage(); + if (lstat(argv[1], &sb) == 0) + errc(1, EEXIST, "%s", argv[1]); + /* + * We could simply call link(2) here, but linkit() + * performs additional checks and gives better + * diagnostics. + */ + exit(linkit(argv[0], argv[1], false)); + } + + while ((ch = getopt(argc, argv, "FLPfhinsvw")) != -1) + switch (ch) { + case 'F': + Fflag = true; + break; + case 'L': + Pflag = false; + break; + case 'P': + Pflag = true; + break; + case 'f': + fflag = true; + iflag = false; + wflag = false; + break; + case 'h': + case 'n': + hflag = true; + break; + case 'i': + iflag = true; + fflag = false; + break; + case 's': + sflag = true; + break; + case 'v': + vflag = true; + break; + case 'w': + wflag = true; + break; + case '?': + default: + usage(); + } + + argv += optind; + argc -= optind; + + linkch = sflag ? '-' : '='; + if (!sflag) + Fflag = false; + if (Fflag && !iflag) { + fflag = true; + wflag = false; /* Implied when fflag is true */ + } + + switch (argc) { + case 0: + usage(); + /* NOTREACHED */ + case 1: /* ln source */ + exit(linkit(argv[0], ".", true)); + case 2: /* ln source target */ + exit(linkit(argv[0], argv[1], false)); + default: + ; + } + /* ln source1 source2 directory */ + targetdir = argv[argc - 1]; + if (hflag && lstat(targetdir, &sb) == 0 && S_ISLNK(sb.st_mode)) { + /* + * We were asked not to follow symlinks, but found one at + * the target--simulate "not a directory" error + */ + errno = ENOTDIR; + err(1, "%s", targetdir); + } + if (stat(targetdir, &sb)) + err(1, "%s", targetdir); + if (!S_ISDIR(sb.st_mode)) + usage(); + for (exitval = 0; *argv != targetdir; ++argv) + exitval |= linkit(*argv, targetdir, true); + exit(exitval); +} + +/* + * Two pathnames refer to the same directory entry if the directories match + * and the final components' names match. + */ +static int +samedirent(const char *path1, const char *path2) +{ + const char *file1, *file2; + char pathbuf[PATH_MAX]; + struct stat sb1, sb2; + + if (strcmp(path1, path2) == 0) + return 1; + file1 = strrchr(path1, '/'); + if (file1 != NULL) + file1++; + else + file1 = path1; + file2 = strrchr(path2, '/'); + if (file2 != NULL) + file2++; + else + file2 = path2; + if (strcmp(file1, file2) != 0) + return 0; + if (file1 - path1 >= PATH_MAX || file2 - path2 >= PATH_MAX) + return 0; + if (file1 == path1) + memcpy(pathbuf, ".", 2); + else { + memcpy(pathbuf, path1, file1 - path1); + pathbuf[file1 - path1] = '\0'; + } + if (stat(pathbuf, &sb1) != 0) + return 0; + if (file2 == path2) + memcpy(pathbuf, ".", 2); + else { + memcpy(pathbuf, path2, file2 - path2); + pathbuf[file2 - path2] = '\0'; + } + if (stat(pathbuf, &sb2) != 0) + return 0; + return sb1.st_dev == sb2.st_dev && sb1.st_ino == sb2.st_ino; +} + +/* + * Create a link to source. If target is a directory (and some additional + * conditions apply, see comments within) the link will be created within + * target and have the basename of source. Otherwise, the link will be + * named target. If isdir is true, target has already been determined to + * be a directory; otherwise, we will check, if needed. + */ +static int +linkit(const char *source, const char *target, bool isdir) +{ + char path[PATH_MAX]; + char wbuf[PATH_MAX]; + char bbuf[PATH_MAX]; + struct stat sb; + const char *p; + int ch, first; + bool append, exists; + + if (!sflag) { + /* If source doesn't exist, quit now. */ + if ((Pflag ? lstat : stat)(source, &sb)) { + warn("%s", source); + return (1); + } + /* Only symbolic links to directories. */ + if (S_ISDIR(sb.st_mode)) { + errno = EISDIR; + warn("%s", source); + return (1); + } + } + + /* + * Append a slash and the source's basename if: + * - the target is "." or ends in "/" or "/.", or + * - the target is a directory (and not a symlink if hflag) and + * Fflag is not set + */ + if ((p = strrchr(target, '/')) == NULL) + p = target; + else + p++; + append = false; + if (p[0] == '\0' || (p[0] == '.' && p[1] == '\0')) { + append = true; + } else if (!Fflag) { + if (isdir || (lstat(target, &sb) == 0 && S_ISDIR(sb.st_mode)) || + (!hflag && stat(target, &sb) == 0 && S_ISDIR(sb.st_mode))) { + append = true; + } + } + if (append) { + if (strlcpy(bbuf, source, sizeof(bbuf)) >= sizeof(bbuf) || + (p = basename(bbuf)) == NULL /* can't happen */ || + snprintf(path, sizeof(path), "%s/%s", target, p) >= + (ssize_t)sizeof(path)) { + errno = ENAMETOOLONG; + warn("%s", source); + return (1); + } + target = path; + } + + /* + * If the link source doesn't exist, and a symbolic link was + * requested, and -w was specified, give a warning. + */ + if (sflag && wflag) { + if (*source == '/') { + /* Absolute link source. */ + if (stat(source, &sb) != 0) + warn("warning: %s inaccessible", source); + } else { + /* + * Relative symlink source. Try to construct the + * absolute path of the source, by appending `source' + * to the parent directory of the target. + */ + strlcpy(bbuf, target, sizeof(bbuf)); + p = dirname(bbuf); + if (p != NULL) { + (void)snprintf(wbuf, sizeof(wbuf), "%s/%s", + p, source); + if (stat(wbuf, &sb) != 0) + warn("warning: %s", source); + } + } + } + + /* + * If the file exists, first check it is not the same directory entry. + */ + exists = lstat(target, &sb) == 0; + if (exists) { + if (!sflag && samedirent(source, target)) { + warnx("%s and %s are the same directory entry", + source, target); + return (1); + } + } + /* + * Then unlink it forcibly if -f was specified + * and interactively if -i was specified. + */ + if (fflag && exists) { + if (Fflag && S_ISDIR(sb.st_mode)) { + if (rmdir(target)) { + warn("%s", target); + return (1); + } + } else if (unlink(target)) { + warn("%s", target); + return (1); + } + } else if (iflag && exists) { + fflush(stdout); + fprintf(stderr, "replace %s? ", target); + + first = ch = getchar(); + while(ch != '\n' && ch != EOF) + ch = getchar(); + if (first != 'y' && first != 'Y') { + fprintf(stderr, "not replaced\n"); + return (1); + } + + if (Fflag && S_ISDIR(sb.st_mode)) { + if (rmdir(target)) { + warn("%s", target); + return (1); + } + } else if (unlink(target)) { + warn("%s", target); + return (1); + } + } + + /* Attempt the link. */ + if (sflag ? symlink(source, target) : + linkat(AT_FDCWD, source, AT_FDCWD, target, + Pflag ? 0 : AT_SYMLINK_FOLLOW)) { + warn("%s", target); + return (1); + } + if (vflag) + (void)printf("%s %c> %s\n", target, linkch, source); + return (0); +} + +static void +link_usage(void) +{ + (void)fprintf(stderr, "usage: link source_file target_file\n"); + exit(1); +} + +static void +usage(void) +{ + (void)fprintf(stderr, "%s\n%s\n", + "usage: ln [-s [-F] | -L | -P] [-f | -i] [-hnv] source_file [target_file]", + " ln [-s [-F] | -L | -P] [-f | -i] [-hnv] source_file ... target_dir"); + exit(1); +} diff --git a/bin/ln/symlink.7 b/bin/ln/symlink.7 new file mode 100644 index 000000000000..28d9908f2053 --- /dev/null +++ b/bin/ln/symlink.7 @@ -0,0 +1,481 @@ +.\"- +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 11, 2024 +.Dt SYMLINK 7 +.Os +.Sh NAME +.Nm symlink +.Nd symbolic link handling +.Sh SYMBOLIC LINK HANDLING +Symbolic links are files that act as pointers to other files. +To understand their behavior, you must first understand how hard links +work. +A hard link to a file is indistinguishable from the original file because +it is a reference to the object underlying the original file name. +Changes to a file are independent of the name used to reference the +file. +Hard links may not refer to directories and may not reference files +on different file systems. +A symbolic link contains the name of the file to which it is linked, +i.e., it is a pointer to another name, and not to an underlying object. +For this reason, symbolic links may reference directories and may span +file systems. +.Pp +Because a symbolic link and its referenced object coexist in the file system +name space, confusion can arise in distinguishing between the link itself +and the referenced object. +Historically, commands and system calls have adopted their own link +following conventions in a somewhat ad-hoc fashion. +Rules for more a uniform approach, as they are implemented in this system, +are outlined here. +It is important that local applications conform to these rules, too, +so that the user interface can be as consistent as possible. +.Pp +Symbolic links are handled either by operating on the link itself, +or by operating on the object referenced by the link. +In the latter case, +an application or system call is said to +.Dq follow +the link. +Symbolic links may reference other symbolic links, +in which case the links are dereferenced until an object that is +not a symbolic link is found, +a symbolic link which references a file which does not exist is found, +or a loop is detected. +(Loop detection is done by placing an upper limit on the number of +links that may be followed, and an error results if this limit is +exceeded.) +.Pp +There are three separate areas that need to be discussed. +They are as follows: +.Pp +.Bl -enum -compact -offset indent +.It +Symbolic links used as file name arguments for system calls. +.It +Symbolic links specified as command line arguments to utilities that +are not traversing a file tree. +.It +Symbolic links encountered by utilities that are traversing a file tree +(either specified on the command line or encountered as part of the +file hierarchy walk). +.El +.Ss System calls. +The first area is symbolic links used as file name arguments for +system calls. +.Pp +Except as noted below, all system calls follow symbolic links. +For example, if there were a symbolic link +.Dq Li slink +which pointed to a file named +.Dq Li afile , +the system call +.Dq Li open("slink" ...\&) +would return a file descriptor to the file +.Dq afile . +.Pp +There are thirteen system calls that do not follow links, and which operate +on the symbolic link itself. +They are: +.Xr lchflags 2 , +.Xr lchmod 2 , +.Xr lchown 2 , +.Xr lpathconf 2 , +.Xr lstat 2 , +.Xr lutimes 2 , +.Xr readlink 2 , +.Xr readlinkat 2 , +.Xr rename 2 , +.Xr renameat 2 , +.Xr rmdir 2 , +.Xr unlink 2 , +and +.Xr unlinkat 2 . +Because +.Xr remove 3 +is an alias for +.Xr unlink 2 , +it also does not follow symbolic links. +When +.Xr rmdir 2 +or +.Xr unlinkat 2 +with the +.Dv AT_REMOVEDIR +flag +is applied to a symbolic link, it fails with the error +.Er ENOTDIR . +.Pp +The +.Xr linkat 2 +system call does not follow symbolic links +unless given the +.Dv AT_SYMLINK_FOLLOW +flag. +.Pp +The following system calls follow symbolic links +unless given the +.Dv AT_SYMLINK_NOFOLLOW +flag: +.Xr chflagsat 2 , +.Xr faccessat 2 , +.Xr fchmodat 2 , +.Xr fchownat 2 , +.Xr fstatat 2 +and +.Xr utimensat 2 . +.Pp +The owner and group of an existing symbolic link can be changed by +means of the +.Xr lchown 2 +system call. +The flags, access permissions, owner/group and modification time of +an existing symbolic link can be changed by means of the +.Xr lchflags 2 , +.Xr lchmod 2 , +.Xr lchown 2 , +and +.Xr lutimes 2 +system calls, respectively. +Of these, only the flags and ownership are used by the system; +the access permissions are ignored. +.Pp +The +.Bx 4.4 +system differs from historical +.Bx 4 +systems in that the system call +.Xr chown 2 +has been changed to follow symbolic links. +The +.Xr lchown 2 +system call was added later when the limitations of the new +.Xr chown 2 +became apparent. +.Ss Commands not traversing a file tree. +The second area is symbolic links, specified as command line file +name arguments, to commands which are not traversing a file tree. +.Pp +Except as noted below, commands follow symbolic links named as command +line arguments. +For example, if there were a symbolic link +.Dq Li slink +which pointed to a file named +.Dq Li afile , +the command +.Dq Li cat slink +would display the contents of the file +.Dq Li afile . +.Pp +It is important to realize that this rule includes commands which may +optionally traverse file trees, e.g.\& the command +.Dq Li "chown file" +is included in this rule, while the command +.Dq Li "chown -R file" +is not. +(The latter is described in the third area, below.) +.Pp +If it is explicitly intended that the command operate on the symbolic +link instead of following the symbolic link, e.g., it is desired that +.Dq Li "chown slink" +change the ownership of the file that +.Dq Li slink +is, whether it is a symbolic link or not, the +.Fl h +option should be used. +In the above example, +.Dq Li "chown root slink" +would change the ownership of the file referenced by +.Dq Li slink , +while +.Dq Li "chown -h root slink" +would change the ownership of +.Dq Li slink +itself. +.Pp +There are five exceptions to this rule. +The +.Xr mv 1 +and +.Xr rm 1 +commands do not follow symbolic links named as arguments, +but respectively attempt to rename and delete them. +(Note, if the symbolic link references a file via a relative path, +moving it to another directory may very well cause it to stop working, +since the path may no longer be correct.) +.Pp +The +.Xr ls 1 +command is also an exception to this rule. +For compatibility with historic systems (when +.Nm ls +is not doing a tree walk, i.e., the +.Fl R +option is not specified), +the +.Nm ls +command follows symbolic links named as arguments if the +.Fl H +or +.Fl L +option is specified, +or if the +.Fl F , +.Fl d +or +.Fl l +options are not specified. +(The +.Nm ls +command is the only command where the +.Fl H +and +.Fl L +options affect its behavior even though it is not doing a walk of +a file tree.) +.Pp +The +.Xr file 1 +and +.Xr stat 1 +commands are also exceptions to this rule. +These +commands do not follow symbolic links named as argument by default, +but do follow symbolic links named as argument if the +.Fl L +option is specified. +.Pp +The +.Bx 4.4 +system differs from historical +.Bx 4 +systems in that the +.Nm chown +and +.Nm chgrp +commands follow symbolic links specified on the command line. +.Ss Commands traversing a file tree. +The following commands either optionally or always traverse file trees: +.Xr chflags 1 , +.Xr chgrp 1 , +.Xr chmod 1 , +.Xr cp 1 , +.Xr du 1 , +.Xr find 1 , +.Xr ls 1 , +.Xr pax 1 , +.Xr rm 1 , +.Xr tar 1 +and +.Xr chown 8 . +.Pp +It is important to realize that the following rules apply equally to +symbolic links encountered during the file tree traversal and symbolic +links listed as command line arguments. +.Pp +The first rule applies to symbolic links that reference files that are +not of type directory. +Operations that apply to symbolic links are performed on the links +themselves, but otherwise the links are ignored. +.Pp +The command +.Dq Li "rm -r slink directory" +will remove +.Dq Li slink , +as well as any symbolic links encountered in the tree traversal of +.Dq Li directory , +because symbolic links may be removed. +In no case will +.Nm rm +affect the file which +.Dq Li slink +references in any way. +.Pp +The second rule applies to symbolic links that reference files of type +directory. +Symbolic links which reference files of type directory are never +.Dq followed +by default. +This is often referred to as a +.Dq physical +walk, as opposed to a +.Dq logical +walk (where symbolic links referencing directories are followed). +.Pp +As consistently as possible, you can make commands doing a file tree +walk follow any symbolic links named on the command line, regardless +of the type of file they reference, by specifying the +.Fl H +(for +.Dq half\-logical ) +flag. +This flag is intended to make the command line name space look +like the logical name space. +(Note, for commands that do not always do file tree traversals, the +.Fl H +flag will be ignored if the +.Fl R +flag is not also specified.) +.Pp +For example, the command +.Dq Li "chown -HR user slink" +will traverse the file hierarchy rooted in the file pointed to by +.Dq Li slink . +Note, the +.Fl H +is not the same as the previously discussed +.Fl h +flag. +The +.Fl H +flag causes symbolic links specified on the command line to be +dereferenced both for the purposes of the action to be performed +and the tree walk, and it is as if the user had specified the +name of the file to which the symbolic link pointed. +.Pp +As consistently as possible, you can make commands doing a file tree +walk follow any symbolic links named on the command line, as well as +any symbolic links encountered during the traversal, regardless of +the type of file they reference, by specifying the +.Fl L +(for +.Dq logical ) +flag. +This flag is intended to make the entire name space look like +the logical name space. +(Note, for commands that do not always do file tree traversals, the +.Fl L +flag will be ignored if the +.Fl R +flag is not also specified.) +.Pp +For example, the command +.Dq Li "chown -LR user slink" +will change the owner of the file referenced by +.Dq Li slink . +If +.Dq Li slink +references a directory, +.Nm chown +will traverse the file hierarchy rooted in the directory that it +references. +In addition, if any symbolic links are encountered in any file tree that +.Nm chown +traverses, they will be treated in the same fashion as +.Dq Li slink . +.Pp +As consistently as possible, you can specify the default behavior by +specifying the +.Fl P +(for +.Dq physical ) +flag. +This flag is intended to make the entire name space look like the +physical name space. +.Pp +For commands that do not by default do file tree traversals, the +.Fl H , +.Fl L +and +.Fl P +flags are ignored if the +.Fl R +flag is not also specified. +In addition, you may specify the +.Fl H , +.Fl L +and +.Fl P +options more than once; the last one specified determines the +command's behavior. +This is intended to permit you to alias commands to behave one way +or the other, and then override that behavior on the command line. +.Pp +The +.Xr ls 1 +and +.Xr rm 1 +commands have exceptions to these rules. +The +.Nm rm +command operates on the symbolic link, and not the file it references, +and therefore never follows a symbolic link. +The +.Nm rm +command does not support the +.Fl H , +.Fl L +or +.Fl P +options. +.Pp +To maintain compatibility with historic systems, +the +.Nm ls +command acts a little differently. +If you do not specify the +.Fl F , +.Fl d +or +.Fl l +options, +.Nm ls +will follow symbolic links specified on the command line. +If the +.Fl L +flag is specified, +.Nm ls +follows all symbolic links, +regardless of their type, +whether specified on the command line or encountered in the tree walk. +.Sh SEE ALSO +.Xr chflags 1 , +.Xr chgrp 1 , +.Xr chmod 1 , +.Xr cp 1 , +.Xr du 1 , +.Xr find 1 , +.Xr ln 1 , +.Xr ls 1 , +.Xr mv 1 , +.Xr pax 1 , +.Xr rm 1 , +.Xr tar 1 , +.Xr lchflags 2 , +.Xr lchmod 2 , +.Xr lchown 2 , +.Xr lstat 2 , +.Xr lutimes 2 , +.Xr readlink 2 , +.Xr rename 2 , +.Xr symlink 2 , +.Xr unlink 2 , +.Xr fts 3 , +.Xr remove 3 , +.Xr chown 8 diff --git a/bin/ln/tests/Makefile b/bin/ln/tests/Makefile new file mode 100644 index 000000000000..13ae71b73143 --- /dev/null +++ b/bin/ln/tests/Makefile @@ -0,0 +1,3 @@ +ATF_TESTS_SH+= ln_test + +.include <bsd.test.mk> diff --git a/bin/ln/tests/Makefile.depend b/bin/ln/tests/Makefile.depend new file mode 100644 index 000000000000..11aba52f82cf --- /dev/null +++ b/bin/ln/tests/Makefile.depend @@ -0,0 +1,10 @@ +# Autogenerated - do NOT edit! + +DIRDEPS = \ + + +.include <dirdeps.mk> + +.if ${DEP_RELDIR} == ${_DEP_RELDIR} +# local dependencies - needed for -jN in clean tree +.endif diff --git a/bin/ln/tests/ln_test.sh b/bin/ln/tests/ln_test.sh new file mode 100644 index 000000000000..ac9d785ba1fc --- /dev/null +++ b/bin/ln/tests/ln_test.sh @@ -0,0 +1,295 @@ +# +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright 2017 Shivansh Rai +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +# SUCH DAMAGE. +# + +atf_check_same_file() +{ + atf_check test "$1" -ef "$2" +} + +atf_check_symlink_to() +{ + atf_check -o inline:"$1\n" readlink "$2" +} + +atf_test_case L_flag +L_flag_head() +{ + atf_set "descr" "Verify that when creating a hard link to a " \ + "symbolic link, '-L' option creates a hard" \ + "link to the target of the symbolic link" +} +L_flag_body() +{ + atf_check touch A + atf_check ln -s A B + atf_check ln -L B C + atf_check_same_file A C + atf_check_symlink_to A B +} + +atf_test_case P_flag +P_flag_head() +{ + atf_set "descr" "Verify that when creating a hard link to a " \ + "symbolic link, '-P' option creates a hard " \ + "link to the symbolic link itself" +} +P_flag_body() +{ + atf_check touch A + atf_check ln -s A B + atf_check ln -P B C + atf_check_same_file B C +} + +atf_test_case f_flag +f_flag_head() +{ + atf_set "descr" "Verify that if the target file already exists, " \ + "'-f' option unlinks it so that link may occur" +} +f_flag_body() +{ + atf_check touch A B + atf_check ln -f A B + atf_check_same_file A B +} + +atf_test_case target_exists_hard +target_exists_hard_head() +{ + atf_set "descr" "Verify whether creating a hard link fails if the " \ + "target file already exists" +} +target_exists_hard_body() +{ + atf_check touch A B + atf_check -s exit:1 -e inline:'ln: B: File exists\n' \ + ln A B +} + +atf_test_case target_exists_symbolic +target_exists_symbolic_head() +{ + atf_set "descr" "Verify whether creating a symbolic link fails if " \ + "the target file already exists" +} +target_exists_symbolic_body() +{ + atf_check touch A B + atf_check -s exit:1 -e inline:'ln: B: File exists\n' \ + ln -s A B +} + +atf_test_case shf_flag_dir +shf_flag_dir_head() { + atf_set "descr" "Verify that if the target directory is a symbolic " \ + "link, '-shf' option prevents following the link" +} +shf_flag_dir_body() +{ + atf_check mkdir -m 0777 A B + atf_check ln -s A C + atf_check ln -shf B C + atf_check test -L C + atf_check -o inline:'B\n' readlink C +} + +atf_test_case snf_flag_dir +snf_flag_dir_head() { + atf_set "descr" "Verify that if the target directory is a symbolic " \ + "link, '-snf' option prevents following the link" +} +snf_flag_dir_body() +{ + atf_check mkdir -m 0777 A B + atf_check ln -s A C + atf_check ln -snf B C + atf_check_symlink_to B C +} + +atf_test_case sF_flag +sF_flag_head() +{ + atf_set "descr" "Verify that if the target file already exists " \ + "and is a directory, then '-sF' option removes " \ + "it so that the link may occur" +} +sF_flag_body() +{ + atf_check mkdir A B + atf_check ln -sF A B + atf_check_symlink_to A B +} + +atf_test_case sf_flag +sf_flag_head() +{ + atf_set "descr" "Verify that if the target file already exists, " \ + "'-sf' option unlinks it and creates a symbolic link " \ + "to the source file" +} +sf_flag_body() +{ + atf_check touch A B + atf_check ln -sf A B + atf_check_symlink_to A B +} + +atf_test_case sfF_flag +sfF_flag_head() +{ + atf_set "descr" "Verify that if the target file already exists " \ + "and is a symlink, then '-sfF' option removes " \ + "it so that the link may occur" +} +sfF_flag_body() +{ + atf_check mkdir A B C D D/A + atf_check ln -sF A C + atf_check_symlink_to A C + atf_check ln -sfF B C + atf_check_symlink_to B C + atf_check ln -sfF A D/ + atf_check_symlink_to A D/A + atf_check ln -sfF ../A . + atf_check_symlink_to ../A A +} + +atf_test_case s_flag +s_flag_head() +{ + atf_set "descr" "Verify that '-s' option creates a symbolic link" +} +s_flag_body() +{ + atf_check touch A + atf_check ln -s A B + atf_check_symlink_to A B +} + +atf_test_case s_flag_broken +s_flag_broken_head() +{ + atf_set "descr" "Verify that if the source file does not exists, '-s' " \ + "option creates a broken symbolic link to the source file" +} +s_flag_broken_body() +{ + atf_check ln -s A B + atf_check_symlink_to A B +} + +atf_test_case sw_flag +sw_flag_head() +{ + atf_set "descr" "Verify that '-sw' option produces a warning if the " \ + "source of a symbolic link does not currently exist" +} +sw_flag_body() +{ + atf_check -s exit:0 -e inline:'ln: warning: A: No such file or directory\n' \ + ln -sw A B + atf_check_symlink_to A B +} + +atf_test_case link_argc +link_argc_head() { + atf_set "descr" "Verify that link(1) requires exactly two arguments" +} +link_argc_body() { + atf_check -s exit:1 -e match:"usage: link" \ + link foo + atf_check -s exit:1 -e match:"No such file" \ + link foo bar + atf_check -s exit:1 -e match:"No such file" \ + link -- foo bar + atf_check -s exit:1 -e match:"usage: link" \ + link foo bar baz +} + +atf_test_case link_basic +link_basic_head() { + atf_set "descr" "Verify that link(1) creates a link" +} +link_basic_body() { + touch foo + atf_check link foo bar + atf_check_same_file foo bar + rm bar + ln -s foo bar + atf_check link bar baz + atf_check_same_file foo baz +} + +atf_test_case link_eexist +link_eexist_head() { + atf_set "descr" "Verify that link(1) fails if the target exists" +} +link_eexist_body() { + touch foo bar + atf_check -s exit:1 -e match:"bar.*exists" \ + link foo bar + ln -s non-existent baz + atf_check -s exit:1 -e match:"baz.*exists" \ + link foo baz +} + +atf_test_case link_eisdir +link_eisdir_head() { + atf_set "descr" "Verify that link(1) fails if the source is a directory" +} +link_eisdir_body() { + mkdir foo + atf_check -s exit:1 -e match:"foo.*directory" \ + link foo bar + ln -s foo bar + atf_check -s exit:1 -e match:"bar.*directory" \ + link bar baz +} + +atf_init_test_cases() +{ + atf_add_test_case L_flag + atf_add_test_case P_flag + atf_add_test_case f_flag + atf_add_test_case target_exists_hard + atf_add_test_case target_exists_symbolic + atf_add_test_case shf_flag_dir + atf_add_test_case snf_flag_dir + atf_add_test_case sF_flag + atf_add_test_case sf_flag + atf_add_test_case sfF_flag + atf_add_test_case s_flag + atf_add_test_case s_flag_broken + atf_add_test_case sw_flag + atf_add_test_case link_argc + atf_add_test_case link_basic + atf_add_test_case link_eexist + atf_add_test_case link_eisdir +} |