This bug is entered to enable getting these API extensions downstream to RHS 2.1 U2 as a part of nfs-ganesha tech preview to be released with U2.

Some points to note on impact of the change (QE/Component owners):
------------------------------------------------------------------
1) This change will up the gfapi version from the current downstream #4 to #5 in the pkgconfig file for glusterfs-devel.pc file.

2) Although the version is upped, there is no change to existing interfaces, which means other consumers of gfapi will continue to compile and/or run with these changes in place as well.
NOTE: Unless there is a strong pkgconfig version for glusterfs-api to be _equal_ to 4.

3) We _may_ need a sanity or functional coverage of gfapi consumers even though (2) is true, to ensure nothing is broken.

4) The change also introduces a slight shift in all SYNCOPs as explained below in "SYNCOP Impact" below.

5) Due to (4) we may need other SYNCOP consumers tested to ensure things are in place.

6) Additional threads of information,
   - gluster devel thread on this addition: http://lists.gnu.org/archive/html/gluster-devel/2013-09/msg00070.html
   - Upstream bug from which this is cloned: #1016000
   - Upstream gerrit link: http://review.gluster.org/#/c/5936/
   - nfs-ganesha upstream branch that integrates these additional changes to enable gluster integration to the Ganesha NFS server: https://github.com/nfs-ganesha/nfs-ganesha/tree/next

SYNCOP Impact:
--------------
The SYNCOP function syncop_create_frame, that creates syncop frames for nonSYNCENV threads is modified to accept thread specific UID/GID/Groups as set by the newly introduced gf APIs: glfs_setfsuid, glfs_setfsgid, glfs_setfsgroups.

This change does not impact consumers of SYNCOPs that operate outside the SYNCENV as they would not be setting these thread variables and hence would continue to operate with the previous behaviour of SYNCOPs. _Only_ gfapi consumers that use these glfs_setfsXXX variants would change what UID/GID/Groups get passed to the syncop from the frame thus created.

Hence, the changes made in the patch set as pointed upstream is backward compatible, but, prudence necessitates that some sanity tests for other SYNCOP consumers be covered as a part of the release to ensure that nothing is broken.


+++ This bug was initially created as a clone of Bug #1016000 +++

Description of problem:

gfapi: object handle based API extensions

There is an ongoing effort to integrate NFS Ganesha (
https://github.com/nfs-ganesha/nfs-ganesha/wiki ) with GlusterFS as one of
the file system back ends.

Towards this we need extensions to gfapi that can handle object based
operations. Meaning, instead of using full paths or relative paths from
cwd, it is required that we can work with APIs, like the *at POSIX
variants, to be able to create, lookup, open etc. files and directories.
Hence the objects are the files or directories themselves and we give out
handles to these objects that can be used for further operations.

The new APIs are implemented as glfs_h_XXX variants in the file
glfs-handleops.c to mirror glfs-fops.c style. The code leverages holding
onto inode references and doling these out as opaque/cookie type objects to
the callers, to enable them to be used as handles in other operations.

An fd based approach was considered, but due to the extra footprint that
the fd structure and its counterparts would incur, this was dropped to take
the approach of holding inode references themselves.

Tested by extending glfsxmp.c to invoke and exercise the added APIs, and
further tested with a reference integration of the same as an FSAL with NFS
Ganesha.

Initial code drop for the same can be seen here, http://review.gluster.com/#/c/5936/

Version-Release number of selected component (if applicable):


How reproducible:


Steps to Reproduce:
1.
2.
3.

Actual results:


Expected results:


Additional info:

--- Additional comment from Anand Avati on 2013-10-07 06:34:17 EDT ---

REVIEW: http://review.gluster.org/5936 (gfapi: object handle based API extensions) posted (#6) for review on master by Shyamsundar Ranganathan (srangana@redhat.com)

--- Additional comment from Anand Avati on 2013-10-09 06:51:35 EDT ---

REVIEW: http://review.gluster.org/5936 (gfapi: object handle based API extensions) posted (#7) for review on master by Shyamsundar Ranganathan (srangana@redhat.com)

--- Additional comment from Anand Avati on 2013-10-11 05:35:22 EDT ---

REVIEW: http://review.gluster.org/5936 (gfapi: object handle based API extensions) posted (#8) for review on master by Shyamsundar Ranganathan (srangana@redhat.com)

--- Additional comment from Anand Avati on 2013-10-11 15:16:58 EDT ---

COMMIT: http://review.gluster.org/5936 committed in master by Anand Avati (avati@redhat.com) 
------
commit d573f170cf3305c066f8b191f872d2d2f22f2025
Author: R.Shyamsundar <srangana@redhat.com>
Date:   Mon Sep 16 16:39:24 2013 +0530

    gfapi: object handle based API extensions
    
    There is an ongoing effort to integrate NFS Ganesha (
    https://github.com/nfs-ganesha/nfs-ganesha/wiki ) with GlusterFS as one of
    the file system back ends.
    
    Towards this we need extensions to gfapi that can handle object based
    operations. Meaning, instead of using full paths or relative paths from
    cwd, it is required that we can work with APIs, like the *at POSIX
    variants, to be able to create, lookup, open etc. files and directories.
    Hence the objects are the files or directories themselves and we give out
    handles to these objects that can be used for further operations.
    
    This code drop is an initial implementation of the proposed APIs.
    
    The new APIs are implemented as glfs_h_XXX variants in the file
    glfs-handleops.c to mirror glfs-fops.c style. The code leverages holding
    onto inode references and doling these out as opaque/cookie type objects to
    the callers, to enable them to be used as handles in other operations.
    
    An fd based approach was considered, but due to the extra footprint that
    the fd structure and its counterparts would incur, this was dropped to take
    the approach of holding inode references themselves.
    
    Tested by extending glfsxmp.c to invoke and exercise the added APIs, and
    further tested with a reference integration of the same as an FSAL with NFS
    Ganesha.
    
    Change-Id: I23629c99e905b54070fa2e6565147812e5f3fa5d
    BUG: 1016000
    Signed-off-by: R.Shyamsundar <srangana@redhat.com>
    Reviewed-on: http://review.gluster.org/5936
    Tested-by: Gluster Build System <jenkins@build.gluster.com>
    Reviewed-by: Anand Avati <avati@redhat.com>