Overview
readlink prints the target stored in a symbolic link, which is the text you gave to ln -s. It prints nothing and fails for a file that is not a link. With -f it instead follows every link in a path and prints the final absolute path.
Background
The macOS manual gives no date for the first appearance of readlink. Today the name covers GNU readlink, the readlink that macOS ships, and the readlink applet in BusyBox. They agree on printing a link's target and on -f; the other options differ.
Examples
Show the target of a link, exactly as stored:
ln -s notes.txt link && readlink link
Resolve a path through every link to its absolute name, then show only the final part:
ln -s notes.txt link && basename "$(readlink -f link)"
Use the failure on a file that is not a link:
readlink notes.txt || echo not a link
Show a relative link as stored, which can differ from where it leads:
ln -s ../notes.txt projects/up && readlink projects/up
Options
-f
Follow every link in the path, as far as it goes, and print the absolute path of the result. All but
the last part of the path must exist.
Common mistakes
Plain readlink shows only one step: if a points to b and b points to c, it prints b. Use -f for the final target. A file that is not a link produces no output and exit status 1, which is easy to miss in a script.
Portability
Only the plain form and -f are in the Common examples. GNU's -e, -m, -n and -z are not shared by every implementation. The Common examples were executed on GNU coreutils 9.11, macOS system tools, and BusyBox 1.37.0 (see the development guide for the exact check).
About macOS readlink
This is the readlink in /usr/bin on macOS. It follows the BSD implementation, with -f and -n available on current releases.
Apple notes
macOS readlink has -f and -n; it does not have GNU's -e and -m.
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.