# ln

_Peios / Using Peios / Peiosutils / Files and directories_

> Create hard links and symbolic links between files.

`ln` creates **links** — extra ways to reach a file.

```
ln [options] target link_name
ln [options] target
ln [options] target... directory
ln [options] -t directory target...
```

```
$ ln -s /opt/app/bin/app /lcl/bin/app   # a symbolic link
$ ln data.csv data-archive.csv                # a hard link
```

## Hard links and symbolic links

There are two kinds of link, and they are genuinely different things.

A **hard link** is another name for the *same file*. The file's data exists once; a hard link is an additional directory entry pointing at it. Every hard link to a file is equal — none is "the original" — and the file's data stays as long as at least one hard link remains. Hard links cannot span file systems, and cannot be made to directories.

A **symbolic link** is a small file that simply *contains a path*. When something opens a symbolic link, it is redirected to whatever that path names. The symbolic link and its target are separate files: if the target is moved or removed, the link still exists but now points at nothing — it "dangles". Symbolic links can point anywhere, across file systems and at directories.

`ln` creates **hard links by default**, and symbolic links with `-s`. When in doubt, `-s` — a symbolic link's behaviour is the easier one to reason about.

The two also differ in how they are secured. A hard link is not a new file, so creating one involves no new [security descriptor](/peios/security-fundamentals/security-descriptors/overview.md) — every name for the file shares the file's existing one. A symbolic link *is* a new file, and like any new file it inherits its own descriptor from the directory it is created in.

## The forms

- `ln target link_name` — create one link named `link_name`.
- `ln target` — create a link to `target` in the current directory, with the same final name.
- `ln target... directory` — create a link to each `target` inside `directory`.
- `ln -t directory target...` — the same, with the directory named first.

## Options

| Option | Effect |
|---|---|
| `-s`, `--symbolic` | Make symbolic links instead of hard links. |
| `-f`, `--force` | Remove an existing destination file so the link can be created. |
| `-i`, `--interactive` | Ask before removing an existing destination. |
| `-r`, `--relative` | For a symbolic link, write the target as a path relative to the link's own location, rather than an absolute path. |
| `-n`, `--no-dereference` | If `link_name` is itself a symbolic link to a directory, treat it as an ordinary file — replace the link rather than create something inside the directory it points to. |
| `-L`, `--logical` | When the target is a symbolic link, link to what it points to. |
| `-P`, `--physical` | Make a hard link to a symbolic link itself, rather than to its target. |
| `-t`, `--target-directory=DIR` | Create all links inside `DIR`. |
| `-T`, `--no-target-directory` | Treat `link_name` as a plain file, never as a directory to create links inside. |
| `-b`, `--backup[=CONTROL]` | Back up an existing destination before replacing it. |
| `-S`, `--suffix=SUFFIX` | Use `SUFFIX` for backup file names. |
| `-v`, `--verbose` | Print the name of each link as it is created. |

## Inspecting links afterwards

[`readlink`](/peios/using-peios/peiosutils/listing-and-paths/readlink.md) prints where a symbolic link points. The low-level [`link`](/peios/using-peios/peiosutils/files-and-directories/link-and-unlink.md) command makes a single hard link with no options, for scripts that want exactly that and nothing else.

## Exit status

| Code | Meaning |
|---|---|
| `0` | Every link was created. |
| `1` | A link could not be created. |

Related content:

- [link and unlink](/peios/using-peios/peiosutils/files-and-directories/link-and-unlink.md)
- [readlink](/peios/using-peios/peiosutils/listing-and-paths/readlink.md)
- [Files and directories](/peios/using-peios/peiosutils/files-and-directories/overview.md)