fspacectl(2): Clarifies the return values

rmacklem@ spotted two things in the system call:

• Upon returning from a successful operation, vop_stddeallocate can update rmsr.r_offset to a value greater than file size. This behavior, although being harmless, can be confusing.
• The EINVAL return value for rqsr.r_offset + rqsr.r_len > OFF_MAX is undocumented.

This commit has the following changes:

• vop_stddeallocate and shm_deallocate to bound the the affected area further by the file size.
• The EINVAL case for rqsr.r_offset + rqsr.r_len > OFF_MAX is documented.
• The fspacectl(2), vn_deallocate(9) and VOP_DEALLOCATE(9)'s return len is explicitly documented the be the value 0, and the return offset is restricted to be the smallest of off + len and current file size suggested by kib@. This semantic allows callers to interact better with potential file size growth after the call.

Sponsored by: The FreeBSD Foundation
Reviewed by: imp, kib
Differential Revision: https://reviews.freebsd.org/D31604