linkinfo()

What is the linkinfo() Function?

The linkinfo() function is a built-in PHP function that checks whether a link actually exists and, on Unix systems, returns the device on which it lives. Specifically, it returns the st_dev field from the C stat structure produced by the lstat() system call — an integer that identifies the device (disk/partition) holding the link.

In practice, linkinfo() is most useful as a quick existence check: if it returns 0 or a positive integer, the link exists; if it returns -1 or false, the path is missing, broken, or inaccessible. Despite the name, it does not return the number of hard links — that information comes from the nlink element of stat() or lstat().

This page covers the function's syntax, return values, a runnable example, common gotchas, and related filesystem functions.

Syntax

linkinfo(string $path): int|false

The function takes a single parameter:

• $path — the path to the symbolic or hard link you want to inspect.

It returns:

• a non-negative integer (the st_dev device identifier) when the link exists,
• -1 when the link cannot be read but lstat partially succeeds, or
• false if $path does not exist or cannot be accessed.

Because 0 is a valid, "truthy-but-falsy" return value on some platforms, always compare with !== false rather than relying on a loose boolean test.

How to Use the linkinfo() Function

Follow these steps:

1. Specify the path to the symbolic link or hard link you want to check.
2. Call linkinfo(), passing the path.
3. Compare the result strictly against false to decide whether the link exists.

The example below creates a real file and a symbolic link to it, then inspects the link with linkinfo():

<?php

// Set up a file and a symbolic link to it in the temp directory.
$target = tempnam(sys_get_temp_dir(), 'tgt');
$link   = sys_get_temp_dir() . '/example_link';

@unlink($link);            // remove a leftover link from a previous run
symlink($target, $link);   // create the symlink

$info = linkinfo($link);

if ($info !== false) {
    echo "The link '$link' exists. Device id (st_dev): $info" . PHP_EOL;
} else {
    echo "The link '$link' does not exist or is inaccessible." . PHP_EOL;
}

// A path that doesn't exist fails: false on most systems, -1 on some
// Unix builds (a warning may also be emitted), so treat both as "missing".
$missing = @linkinfo('/no/such/link');
var_dump($missing === false || $missing === -1); // bool(true) -> "missing"

// Clean up.
unlink($link);
unlink($target);

A typical run prints something like:

The link '/tmp/example_link' exists. Device id (st_dev): 16777220
bool(true)

The exact device id depends on your operating system and filesystem, so don't hard-code it — only its presence is meaningful. For the missing path, PHP returns false on most platforms and -1 on some Unix builds, which is why the example treats both as "not found."

Common Gotchas

• Windows. linkinfo() is not meaningful on Windows and effectively only tells you whether the path is a link. Rely on it for existence, not the device number.
• Use !== false, not !$info. On some systems a valid link returns 0, which a loose check would treat as "missing."
• It doesn't follow the link. linkinfo() inspects the link itself (like lstat), not the file the link points to. A symlink to a deleted target still reports as existing.
• Not for counting hard links. Use stat($path)['nlink'] if you need the hard-link count.

Related Functions

• symlink() — create a symbolic link.
• link() — create a hard link.
• readlink() — return the target a symbolic link points to.
• is_link() — test whether a path is a symbolic link.
• lstat() — full status info for a link without following it.

Conclusion

The linkinfo() function is a lightweight way to confirm that a link exists and to read the device it lives on, mirroring the st_dev field of lstat(). Use it for existence checks (always with a strict !== false comparison), and reach for stat() or is_link() when you need richer details such as the hard-link count or link type.

Practice