/* client operations can possibly return the following error codes */

All operations that use the msgpairarray code can possibly return
-PVFS_EINVAL when invalid arguments are specified, and -PVFS_ENOMEM
when internal memory cannot be allocated.

All client sysint calls that issue non-readonly server operations
(this includes create, remove, I/O write, setattr, crdirent, rmdirent,
chdirent, truncate, and mkdir) can possibly return -PVFS_EAGAIN due to
the server's operation mode.  [ req scheduler check of admin
vs. normal mode ]

All client sysint calls inherit the possible return values listed for
sys-getattr.sm since it's used by them all.

All operations that use the PINT-le-bytefield encoder can possibly
return -PVFS_EINVAL (req or resp specified is invalid) and
-PVFS_ENOSYS (trying to encode an uknown req or resp type), or
-PVFS_EPROTO (the decoding did not complete as expected, or we've
attempted to decode an unknown operation type).

In addition to the operation specific error codes listed below, ALL
sysint operations can potentially return BMI classed PVFS2 error codes
generated from the networking layer:

i.e. PVFS_ERROR_CLASS(-sm_p->error_code) == PVFS_ERROR_BMI
[ persistant communication failure after all retries have been
  exhausted; you *cannot* see this class of error unless all retries
  have already been attempted ]

TODO: have a special 'catch all' communication error code to tell the
caller generically that the communication couldn't be completed in
this case, or leave the specific code to help the caller better deal
with the problem?

-------------
sys-create.sm
-------------
-PVFS_EINVAL
 credentials, parent_ref object, object_name, or resp arguments are
 NULL, attribute mask is invalid (contains non-setable attribute
 bits), specified distribution (if any) name is invalid, or the
 specified dfile_count is invalid (either negative or larger than the
 compile time constant PVFS_REQ_LIMIT_DFILE_COUNT)

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENAMETOOLONG
 object_name length is longer than the compile time constant
 PVFS_REQ_LIMIT_SEGMENT_BYTES

-PVFS_ENOTDIR
 parent object reference is not a directory

-PVFS_EEXIST
 creating the directory entry for the newly created object failed
 because it already exists

-PVFS_ENOENT
 the dirent being created contains invalid or unprintable characters

-------------
sys-flush.sm
------------
-PVFS_EINVAL
 invalid object reference specified

-PVFS_ENOMEM
 system memory allocation failure

-------------
sys-getattr.sm
--------------
-PVFS_EINVAL
 invalid object reference, resp, or attrmask specified; retrieved
 attributes have an unknown type

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENOENT
 the specified object does not exist

NOTE: if the attributes retrieved contain a valid symlink target path,
it MUST be freed by the caller

-------------
sys-io.sm
---------
-PVFS_EINVAL
 invalid object reference, fs_id, resp, or I/O operation type; this
 can also be seen if the object being operated on was removed and the
 attributes cannot be retrieved

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ECANCEL
 the I/O operation was cancelled (possibly) before completion

-PVFS_ENOENT
 the object being operated on was removed (possibly) before completion

-PVFS_EISDIR
 the object specified is a directory

-PVFS_EBADF
 the object specified is of an unknown type (not a file and not a
 directory), or the internal distribution information is invalid; this
 can be possibly be seen if the object being operation on was removed
 and the I/O operation can no longer perform the specified operation

PVFS_ERROR_CLASS(-sm_p->error_code) == PVFS_ERROR_FLOW
[ persistant failure after all retries have been exhausted ]

TODO: make sure flow uses PVFS2 specific error codes rather than
errnos -- wrap them like the BMI codes if not

-------------
sys-lookup.sm
-------------
-PVFS_EINVAL
 credentials, relative pathname, resp, or parent ref are NULL

-PVFS_ENAMETOOLONG
 a segment in the specified pathname is longer than the compile time
 constant PVFS_REQ_LIMIT_SEGMENT_BYTES

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_EMLINK
 there are more symbolic links in the path being resolved than the
 compile time constant PVFS_REQ_LIMIT_MAX_SYMLINK_RESOLUTION_COUNT

-PVFS_ENOENT
 the pathname could not be resolved because it (or one of the path
 components) does not exist

-------------
sys-mkdir.sm
------------
-PVFS_EINVAL
 credentials, parent_ref object, object_name, or resp arguments are
 NULL, or attribute mask is invalid (contains non-setable attribute
 bits)

-PVFS_ENAMETOOLONG
 the specified object_name is longer than the compile time constant
 PVFS_REQ_LIMIT_SEGMENT_BYTES

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENOTDIR
 parent object reference is not a directory

-PVFS_EEXIST
 creating the directory entry for the newly created object failed
 because it already exists

-PVFS_ENOENT
 the dirent being created contains invalid or unprintable characters

-------------
sys-readdir.sm
--------------
-PVFS_EINVAL
 credentials, ref, or resp arguments are NULL, or pvfs_dirent_incount
 is greater than the compile time constant PVFS_REQ_LIMIT_DIRENT_COUNT

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENOTDIR
 parent object reference is not a directory

NOTE: if there are entries in the dirent_array in the response, it
MUST be freed by the caller

-------------
sys-remove.sm
-------------
-PVFS_EINVAL
 credentials, parent_ref, or resp arguments are NULL, or the object
 being removed is of an unkknown type

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENOENT
 the object being removed does not exist

-PVFS_ENOTEMPTY
 the object being removed is a directory that is not empty

-------------
sys-rename.sm
-------------
-PVFS_EINVAL
 credentials, old_parent_ref, new_parent_ref, old_entry, or new_entry
 arguments are NULL; the old_parent_ref and new_parent_ref refer to
 the same object

-PVFS_ENAMETOOLONG
 the new_entry name is longer than the compile time constant
 PVFS_REQ_LIMIT_SEGMENT_BYTES

-PVFS_ENOTDIR
 one of the parent objects specified is not a directory

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENOENT
 the specified old_entry doesn't exist

--------------
sys-setattr.sm
--------------
-PVFS_EINVAL
 credentials, or ref are NULL, or attribute mask is invalid (contains
 non-setable attribute bits)

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_EACCES
 the object specified does not have attributes that can be changed, or
 the object type is unrecognized

-PVFS_EOVERFLOW
 the meta attribute field 'dfile_count' is invalid (either negative
 or larger than the compile time constant PVFS_REQ_LIMIT_DFILE_COUNT)

-PVFS_EPERM
 the credentials supplied are not appropriate for making the requested
 changes

--------------
sys-symlink.sm
--------------
-PVFS_EINVAL
 credentials, parent_ref object, entry_name, target, or resp arguments
 are NULL, or attribute mask is invalid (contains non-setable
 attribute bits)

-PVFS_ENAMETOOLONG
 the specified entry_name OR target is longer than the compile time
 constant PVFS_REQ_LIMIT_SEGMENT_BYTES

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_ENOTDIR
 parent object reference is not a directory

-PVFS_EEXIST
 creating the directory entry for the newly created object failed
 because it already exists

-PVFS_ENOENT
 the dirent being created contains invalid or unprintable characters

---------------
sys-truncate.sm
---------------
-PVFS_EINVAL
 credentials, or ref object is NULL, or size field is negative

-PVFS_ENOMEM
 system memory allocation failure

-PVFS_EISDIR
 the object specified is a directory

-PVFS_EBADF
 the object specified is of an unknown type (not a file and not a
 directory)
