Document the failure mode if size is too small and mention that

Document the failure mode if size is too small and mention that
allocating space when buf is NULL is an extension more prominently.
Clarify that getwd() is deprecated and should not be used.
Mention EFAULT errno value for invalid (non-NULL) buf.
OK deraadt@ jmc@