Here is a puzzle for you. Suppose that you're trying to change your password on a typical Linux system, as happens periodically (and as we make new logins on our systems do immediately), and you get the following:

; passwd
Changing password for user cks.
Current password: 
passwd: Authentication token manipulation error

What has gone wrong here? What should you do to fix it? Should you try again, or instead send email to your system administrators to get them to fix it?

Well, you don't know, because passwd and Linux's implementation of PAM have combined to create a terrible error message through robot logic, where the error message is completely technically logical and correct but useless in practice. The most likely cause of this message is that you've mis-typed your current password, but there are other possible causes if things have gone wrong in the depths of PAM. The only people who can start to disentangle this is your system administrators, or in general anyone who can look at PAM's logs (normally in syslog), because only there will you find extremely valuable and much more precise messages like:

passwd[487312]: pam_unix(passwd:chauthtok): authentication failure; logname= uid=19 euid=0 tty=pts/6 ruser= rhost=  user=cks

Even this isn't really clear, but with sufficient painful experience you can decode this to that the passwd command was verifying your password through traditional Unix /etc/shadow encrypted passwords, and the password you typed didn't 'authenticate', ie didn't match the encrypted password.

One of the reasons this is a terrible error message is because normal people have essentially no chance at all of understanding it (as I can assure you from our experience of supporting the people who use our systems). The best you can do is use a wrapper script that puts a big explanatory message around the whole thing, and even then people get confused.

(And if other things go wrong and the same message gets printed out, you're really confusing people; you've claimed that the problem is that they're using the wrong password, except they know that they're not. At least they'll probably email the system administrators at that point.)

I'm not sure if the PAM API provides any way for PAM modules such as pam_unix to provide a more specific error message. This particular error message is the generic PAM error string for PAM_AUTHTOK_ERR, which is the equally generic PAM error code that pam_unix is forced to return in this situation. You can see the full list in the pam(3) manpage.