The other day I had some exposure to the semantics of link().
Maildir does this neat trick of having separate cur/ new/ and tmp/ subdirectories, with a file per message. To move a message from one to another, it first calls link() to bring it to the new directory, then unlink() to remove it from the old one. This does a good job of keeping mail from getting lost or corrupted, but has a failure mode when the machine goes down between the call to link() and unlink() (not as unlikely as you might think - it could be on an NFS partition).
In the failure case, the message will appear in both boxes. This could easily be cleaned up simply by having the next attempt to link it succeed and the extra file disappear in the process. Unfortunately link() isn't idempotent - it instead fails with the reason that the file already exists. This I find astounding. If someone calls link() on a file which is already linked in exactly the way it's asking, the result should be success with nothing changed, not failure with the reason that the file already exists.
Even worse, non-idempotence isn't just the default behavior, it's the only behavior - there's no option available to make it behave in the sensible way.
I simply cannot fathom what they were thinking.