path: root/doc/hacker-guide/call-stub.txt

creating a call stub and pausing a call
---------------------------------------
libglusterfs provides seperate API to pause each of the fop. parameters to each API is
@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
       NOTE: @fn should exactly take the same type and number of parameters that 
             the corresponding regular fop takes.
rest will be the regular parameters to corresponding fop.

NOTE: @frame can never be NULL. fop_<operation>_stub() fails with errno
      set to EINVAL, if @frame is NULL. also wherever @loc is applicable,
      @loc cannot be NULL.

refer to individual stub creation API to know about call-stub creation's behaviour with
specific parameters.

here is the list of stub creation APIs for xlator fops.

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@loc       - pointer to location structure.
             NOTE: @loc will be copied to a different location, with inode_ref() to
	           @loc->inode and @loc->parent, if not NULL. also @loc->path will be
		   copied to a different location.
@need_xattr - flag to specify if xattr should be returned or not.
call_stub_t *
fop_lookup_stub (call_frame_t *frame,
		 fop_lookup_t fn,
		 loc_t *loc,
		 int32_t need_xattr);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
call_stub_t *
fop_stat_stub (call_frame_t *frame,
	       fop_stat_t fn,
	       loc_t *loc);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to lk fop.
         NOTE: @fd is stored with a fd_ref().
call_stub_t *
fop_fstat_stub (call_frame_t *frame,
		fop_fstat_t fn,
		fd_t *fd);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to @loc->inode and
	       @loc->parent, if not NULL. also @loc->path will be copied to a different location.
@mode  - mode parameter to chmod.
call_stub_t *
fop_chmod_stub (call_frame_t *frame,
		fop_chmod_t fn,
		loc_t *loc,
		mode_t mode);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to lk fop.
         NOTE: @fd is stored with a fd_ref().
@mode  - mode parameter for fchmod fop.
call_stub_t *
fop_fchmod_stub (call_frame_t *frame,
		 fop_fchmod_t fn,
		 fd_t *fd,
		 mode_t mode);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to @loc->inode and
	       @loc->parent, if not NULL. also @loc->path will be copied to a different location.
@uid   - uid parameter to chown.
@gid   - gid parameter to chown.
call_stub_t *
fop_chown_stub (call_frame_t *frame,
		fop_chown_t fn,
		loc_t *loc,
		uid_t uid,
		gid_t gid);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to lk fop.
         NOTE: @fd is stored with a fd_ref().
@uid   - uid parameter to fchown.
@gid   - gid parameter to fchown.
call_stub_t *
fop_fchown_stub (call_frame_t *frame,
		 fop_fchown_t fn,
		 fd_t *fd,
		 uid_t uid,
		 gid_t gid);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location, if not NULL.
@off   - offset parameter to truncate fop.
call_stub_t *
fop_truncate_stub (call_frame_t *frame,
		   fop_truncate_t fn,
		   loc_t *loc,
		   off_t off);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to lk fop.
         NOTE: @fd is stored with a fd_ref().
@off   - offset parameter to ftruncate fop.
call_stub_t *
fop_ftruncate_stub (call_frame_t *frame,
		    fop_ftruncate_t fn,
		    fd_t *fd,
		    off_t off);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@tv    - tv parameter to utimens fop.
call_stub_t *
fop_utimens_stub (call_frame_t *frame,
		  fop_utimens_t fn,
		  loc_t *loc,
		  struct timespec tv[2]);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@mask  - mask parameter for access fop.
call_stub_t *
fop_access_stub (call_frame_t *frame,
		 fop_access_t fn,
		 loc_t *loc,
		 int32_t mask);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@size  - size parameter to readlink fop.
call_stub_t *
fop_readlink_stub (call_frame_t *frame,
		   fop_readlink_t fn,
		   loc_t *loc,
		   size_t size);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@mode  - mode parameter to mknod fop.
@rdev  - rdev parameter to mknod fop.
call_stub_t *
fop_mknod_stub (call_frame_t *frame,
		fop_mknod_t fn,
		loc_t *loc,
		mode_t mode,
		dev_t rdev);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@mode  - mode parameter to mkdir fop.
call_stub_t *
fop_mkdir_stub (call_frame_t *frame,
		fop_mkdir_t fn,
		loc_t *loc,
		mode_t mode);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
call_stub_t *
fop_unlink_stub (call_frame_t *frame,
		 fop_unlink_t fn,
		 loc_t *loc);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
call_stub_t *
fop_rmdir_stub (call_frame_t *frame,
		fop_rmdir_t fn,
		loc_t *loc);

@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@linkname - linkname parameter to symlink fop.
@loc      - pointer to location structure.
            NOTE: @loc will be copied to a different location, with inode_ref() to
	          @loc->inode and @loc->parent, if not NULL. also @loc->path will be
		  copied to a different location.
call_stub_t *
fop_symlink_stub (call_frame_t *frame,
		  fop_symlink_t fn,
		  const char *linkname,
		  loc_t *loc);

@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@oldloc   - pointer to location structure.
            NOTE: @oldloc will be copied to a different location, with inode_ref() to 
	          @oldloc->inode and @oldloc->parent, if not NULL. also @oldloc->path will 
		  be copied to a different location, if not NULL.
@newloc   - pointer to location structure.
            NOTE: @newloc will be copied to a different location, with inode_ref() to
	          @newloc->inode and @newloc->parent, if not NULL. also @newloc->path will
		  be copied to a different location, if not NULL.
call_stub_t *
fop_rename_stub (call_frame_t *frame,
		 fop_rename_t fn,
		 loc_t *oldloc,
		 loc_t *newloc);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc     - pointer to location structure.
           NOTE: @loc will be copied to a different location, with inode_ref() to
	         @loc->inode and @loc->parent, if not NULL. also @loc->path will be
		 copied to a different location.
@newpath - newpath parameter to link fop.
call_stub_t *
fop_link_stub (call_frame_t *frame,
	       fop_link_t fn,
	       loc_t *oldloc,
	       const char *newpath);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@flags - flags parameter to create fop.
@mode  - mode parameter to create fop.
@fd    - file descriptor parameter to create fop.
         NOTE: @fd is stored with a fd_ref().
call_stub_t *
fop_create_stub (call_frame_t *frame,
		 fop_create_t fn,
		 loc_t *loc,
		 int32_t flags,
		 mode_t mode, fd_t *fd);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@flags - flags parameter to open fop.
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
call_stub_t *
fop_open_stub (call_frame_t *frame,
	       fop_open_t fn,
	       loc_t *loc,
	       int32_t flags,
	       fd_t *fd);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to lk fop.
         NOTE: @fd is stored with a fd_ref().
@size  - size parameter to readv fop.
@off   - offset parameter to readv fop.
call_stub_t *
fop_readv_stub (call_frame_t *frame,
		fop_readv_t fn,
		fd_t *fd,
		size_t size,
		off_t off);

@frame  - call frame which has to be used to resume the call at call_resume().
@fn     - procedure to call during call_resume(). 
@fd     - file descriptor parameter to lk fop.
          NOTE: @fd is stored with a fd_ref().
@vector - vector parameter to writev fop. 
	  NOTE: @vector is iov_dup()ed while creating stub. and frame->root->req_refs
                dictionary is dict_ref()ed.
@count  - count parameter to writev fop.
@off    - off parameter to writev fop.
call_stub_t *
fop_writev_stub (call_frame_t *frame,
		 fop_writev_t fn,
		 fd_t *fd,
		 struct iovec *vector,
		 int32_t count,
		 off_t off);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to flush fop.
         NOTE: @fd is stored with a fd_ref().
call_stub_t *
fop_flush_stub (call_frame_t *frame,
		fop_flush_t fn,
		fd_t *fd);


@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@fd       - file descriptor parameter to lk fop.
            NOTE: @fd is stored with a fd_ref().
@datasync - datasync parameter to fsync fop.
call_stub_t *
fop_fsync_stub (call_frame_t *frame,
		fop_fsync_t fn,
		fd_t *fd,
		int32_t datasync);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to @loc->inode and
	       @loc->parent, if not NULL. also @loc->path will be copied to a different location.
@fd    - file descriptor parameter to opendir fop.
         NOTE: @fd is stored with a fd_ref().
call_stub_t *
fop_opendir_stub (call_frame_t *frame,
		  fop_opendir_t fn,
		  loc_t *loc, 
		  fd_t *fd);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to getdents fop.
         NOTE: @fd is stored with a fd_ref().
@size  - size parameter to getdents fop.
@off   - off parameter to getdents fop.
@flags - flags parameter to getdents fop.
call_stub_t *
fop_getdents_stub (call_frame_t *frame,
		   fop_getdents_t fn,
		   fd_t *fd,
		   size_t size,
		   off_t off,
		   int32_t flag);

@frame   - call frame which has to be used to resume the call at call_resume().
@fn      - procedure to call during call_resume(). 
@fd      - file descriptor parameter to setdents fop.
           NOTE: @fd is stored with a fd_ref().
@flags   - flags parameter to setdents fop.
@entries - entries parameter to setdents fop.
call_stub_t *
fop_setdents_stub (call_frame_t *frame,
		   fop_setdents_t fn,
		   fd_t *fd,
		   int32_t flags,
		   dir_entry_t *entries,
		   int32_t count);

@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@fd       - file descriptor parameter to setdents fop.
            NOTE: @fd is stored with a fd_ref().
@datasync - datasync parameter to fsyncdir fop.
call_stub_t *
fop_fsyncdir_stub (call_frame_t *frame,
		   fop_fsyncdir_t fn,
		   fd_t *fd,
		   int32_t datasync);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
call_stub_t *
fop_statfs_stub (call_frame_t *frame,
		 fop_statfs_t fn,
		 loc_t *loc);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to 
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@dict  - dict parameter to setxattr fop.
         NOTE: stub creation procedure stores @dict pointer with dict_ref() to it.
call_stub_t *
fop_setxattr_stub (call_frame_t *frame,
		   fop_setxattr_t fn,
		   loc_t *loc,
		   dict_t *dict,
		   int32_t flags);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@name  - name parameter to getxattr fop.
call_stub_t *
fop_getxattr_stub (call_frame_t *frame,
		   fop_getxattr_t fn,
		   loc_t *loc,
		   const char *name);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@name  - name parameter to removexattr fop.
         NOTE: name string will be copied to a different location while creating stub.
call_stub_t *
fop_removexattr_stub (call_frame_t *frame,
		      fop_removexattr_t fn,
		      loc_t *loc,
		      const char *name);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to lk fop.
         NOTE: @fd is stored with a fd_ref().
@cmd   - command parameter to lk fop.
@lock  - lock parameter to lk fop.
         NOTE: lock will be copied to a different location while creating stub.
call_stub_t *
fop_lk_stub (call_frame_t *frame,
	     fop_lk_t fn,
	     fd_t *fd,
	     int32_t cmd,
	     struct flock *lock);

@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@fd       - fd parameter to gf_lk fop.
	    NOTE: @fd is fd_ref()ed while creating stub, if not NULL.
@cmd      - cmd parameter to gf_lk fop.
@lock     - lock paramater to gf_lk fop.
	    NOTE: @lock is copied to a different memory location while creating
	          stub. 
call_stub_t *
fop_gf_lk_stub (call_frame_t *frame,
		fop_gf_lk_t fn,
		fd_t *fd,
		int32_t cmd,
		struct flock *lock);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@fd    - file descriptor parameter to readdir fop.
         NOTE: @fd is stored with a fd_ref().
@size  - size parameter to readdir fop.
@off   - offset parameter to readdir fop.
call_stub_t *
fop_readdir_stub (call_frame_t *frame,
		  fop_readdir_t fn,
		  fd_t *fd,
		  size_t size,
		  off_t off);

@frame - call frame which has to be used to resume the call at call_resume().
@fn    - procedure to call during call_resume(). 
@loc   - pointer to location structure.
         NOTE: @loc will be copied to a different location, with inode_ref() to
	       @loc->inode and @loc->parent, if not NULL. also @loc->path will be
	       copied to a different location.
@flags - flags parameter to checksum fop.
call_stub_t *
fop_checksum_stub (call_frame_t *frame,
		   fop_checksum_t fn,
		   loc_t *loc,
		   int32_t flags);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@inode     - inode parameter to @fn.
	     NOTE: @inode pointer is stored with a inode_ref().
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
@dict      - dict parameter to @fn.
	     NOTE: @dict pointer is stored with dict_ref().
call_stub_t *
fop_lookup_cbk_stub (call_frame_t *frame,
		     fop_lookup_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     inode_t *inode,
		     struct stat *buf,
		     dict_t *dict);
@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_stat_cbk_stub (call_frame_t *frame,
		   fop_stat_cbk_t fn,
		   int32_t op_ret,
		   int32_t op_errno,
		   struct stat *buf);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_fstat_cbk_stub (call_frame_t *frame,
		    fop_fstat_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    struct stat *buf);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_chmod_cbk_stub (call_frame_t *frame,
		    fop_chmod_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    struct stat *buf);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_fchmod_cbk_stub (call_frame_t *frame,
		     fop_fchmod_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     struct stat *buf);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_chown_cbk_stub (call_frame_t *frame,
		    fop_chown_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_fchown_cbk_stub (call_frame_t *frame,
		     fop_fchown_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_truncate_cbk_stub (call_frame_t *frame,
		       fop_truncate_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno,
		       struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_ftruncate_cbk_stub (call_frame_t *frame,
			fop_ftruncate_cbk_t fn,
			int32_t op_ret,
			int32_t op_errno,
			struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_utimens_cbk_stub (call_frame_t *frame,
		      fop_utimens_cbk_t fn,
		      int32_t op_ret,
		      int32_t op_errno,
		      struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_access_cbk_stub (call_frame_t *frame,
		     fop_access_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@path      - path parameter to @fn.
	     NOTE: @path is copied to a different memory location, if not NULL.
call_stub_t *
fop_readlink_cbk_stub (call_frame_t *frame,
		       fop_readlink_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno,
		       const char *path);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@inode     - inode parameter to @fn.
	     NOTE: @inode pointer is stored with a inode_ref().
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_mknod_cbk_stub (call_frame_t *frame,
		    fop_mknod_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    inode_t *inode,
		    struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@inode     - inode parameter to @fn.
	     NOTE: @inode pointer is stored with a inode_ref().
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_mkdir_cbk_stub (call_frame_t *frame,
		    fop_mkdir_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    inode_t *inode,
		    struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_unlink_cbk_stub (call_frame_t *frame,
		     fop_unlink_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_rmdir_cbk_stub (call_frame_t *frame,
		    fop_rmdir_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@inode     - inode parameter to @fn.
	     NOTE: @inode pointer is stored with a inode_ref().
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_symlink_cbk_stub (call_frame_t *frame,
		      fop_symlink_cbk_t fn,
		      int32_t op_ret,
		      int32_t op_errno,
		      inode_t *inode,
		      struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_rename_cbk_stub (call_frame_t *frame,
		     fop_rename_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@inode     - inode parameter to @fn.
	     NOTE: @inode pointer is stored with a inode_ref().
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_link_cbk_stub (call_frame_t *frame,
		   fop_link_cbk_t fn,
		   int32_t op_ret,
		   int32_t op_errno,
		   inode_t *inode,
		   struct stat *buf);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@fd        - fd parameter to @fn.
	     NOTE: @fd pointer is stored with a fd_ref().
@inode     - inode parameter to @fn.
	     NOTE: @inode pointer is stored with a inode_ref().
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_create_cbk_stub (call_frame_t *frame,
		     fop_create_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     fd_t *fd,
		     inode_t *inode,
		     struct stat *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@fd        - fd parameter to @fn.
	     NOTE: @fd pointer is stored with a fd_ref().
call_stub_t *
fop_open_cbk_stub (call_frame_t *frame,
		   fop_open_cbk_t fn,
		   int32_t op_ret,
		   int32_t op_errno,
		   fd_t *fd);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@vector    - vector parameter to @fn.	
	     NOTE: @vector is copied to a different memory location, if not NULL. also
	           frame->root->rsp_refs is dict_ref()ed.
@stbuf     - stbuf parameter to @fn.
	     NOTE: @stbuf is copied to a different memory location, if not NULL.
call_stub_t *
fop_readv_cbk_stub (call_frame_t *frame,
		    fop_readv_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    struct iovec *vector,
		    int32_t count,
		    struct stat *stbuf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@stbuf     - stbuf parameter to @fn.
	     NOTE: @stbuf is copied to a different memory location, if not NULL.
call_stub_t *
fop_writev_cbk_stub (call_frame_t *frame,
		     fop_writev_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     struct stat *stbuf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_flush_cbk_stub (call_frame_t *frame,
		    fop_flush_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_fsync_cbk_stub (call_frame_t *frame,
		    fop_fsync_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@fd        - fd parameter to @fn.
	     NOTE: @fd pointer is stored with a fd_ref().
call_stub_t *
fop_opendir_cbk_stub (call_frame_t *frame,
		      fop_opendir_cbk_t fn,
		      int32_t op_ret,
		      int32_t op_errno,
		      fd_t *fd);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@entries   - entries parameter to @fn.
@count     - count parameter to @fn.
call_stub_t *
fop_getdents_cbk_stub (call_frame_t *frame,
		      fop_getdents_cbk_t fn,
		      int32_t op_ret,
		      int32_t op_errno,
		      dir_entry_t *entries,
		      int32_t count);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_setdents_cbk_stub (call_frame_t *frame,
		       fop_setdents_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno);

@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_fsyncdir_cbk_stub (call_frame_t *frame,
		       fop_fsyncdir_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@buf       - buf parameter to @fn.
	     NOTE: @buf is copied to a different memory location, if not NULL.
call_stub_t *
fop_statfs_cbk_stub (call_frame_t *frame,
		     fop_statfs_cbk_t fn,
		     int32_t op_ret,
		     int32_t op_errno,
		     struct statvfs *buf);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_setxattr_cbk_stub (call_frame_t *frame,
		       fop_setxattr_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
@value     - value dictionary parameter to @fn.
	     NOTE: @value pointer is stored with a dict_ref().
call_stub_t *
fop_getxattr_cbk_stub (call_frame_t *frame,
		       fop_getxattr_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno,
		       dict_t *value);


@frame     - call frame which has to be used to resume the call at call_resume().
@fn        - procedure to call during call_resume(). 
@op_ret    - op_ret parameter to @fn.
@op_errno  - op_errno parameter to @fn.
call_stub_t *
fop_removexattr_cbk_stub (call_frame_t *frame,
			  fop_removexattr_cbk_t fn,
			  int32_t op_ret,
			  int32_t op_errno);


@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@op_ret   - op_ret parameter to @fn.
@op_errno - op_errno parameter to @fn.
@lock     - lock parameter to @fn.
	    NOTE: @lock is copied to a different memory location while creating
	          stub. 
call_stub_t *
fop_lk_cbk_stub (call_frame_t *frame,
		 fop_lk_cbk_t fn,
		 int32_t op_ret,
		 int32_t op_errno,
		 struct flock *lock);

@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@op_ret   - op_ret parameter to @fn.
@op_errno - op_errno parameter to @fn.
@lock     - lock parameter to @fn.
	    NOTE: @lock is copied to a different memory location while creating
	          stub. 
call_stub_t *
fop_gf_lk_cbk_stub (call_frame_t *frame,
		    fop_gf_lk_cbk_t fn,
		    int32_t op_ret,
		    int32_t op_errno,
		    struct flock *lock);


@frame    - call frame which has to be used to resume the call at call_resume().
@fn       - procedure to call during call_resume(). 
@op_ret   - op_ret parameter to @fn.
@op_errno - op_errno parameter to @fn.
@entries  - entries parameter to @fn.
call_stub_t *
fop_readdir_cbk_stub (call_frame_t *frame,
		      fop_readdir_cbk_t fn,
		      int32_t op_ret,
		      int32_t op_errno,
		      gf_dirent_t *entries);


@frame         - call frame which has to be used to resume the call at call_resume().
@fn            - procedure to call during call_resume(). 
@op_ret        - op_ret parameter to @fn.
@op_errno      - op_errno parameter to @fn.
@file_checksum - file_checksum parameter to @fn.
                 NOTE: file_checksum will be copied to a different memory location 
		       while creating stub.
@dir_checksum  - dir_checksum parameter to @fn.
                 NOTE: file_checksum will be copied to a different memory location 
		       while creating stub.
call_stub_t *
fop_checksum_cbk_stub (call_frame_t *frame,
		       fop_checksum_cbk_t fn,
		       int32_t op_ret,
		       int32_t op_errno,
		       uint8_t *file_checksum,
		       uint8_t *dir_checksum);

resuming a call:
---------------
  call can be resumed using call stub through call_resume API.

  void call_resume (call_stub_t *stub);

  stub - call stub created during pausing a call.

  NOTE: call_resume() will decrease reference count of any fd_t, dict_t and inode_t that it finds
        in  stub->args.<operation>.<fd_t-or-inode_t-or-dict_t>. so, if any fd_t, dict_t or
	inode_t pointers are assigned at stub->args.<operation>.<fd_t-or-inode_t-or-dict_t> after
	fop_<operation>_stub() call, they must be <fd_t-or-inode_t-or-dict_t>_ref()ed.
	
	call_resume does not STACK_DESTROY() for any fop.
	
  if stub->fn is NULL, call_resume does STACK_WIND() or STACK_UNWIND() using the stub->frame.

  return - call resume fails only if stub is NULL. call resume fails with errno set to EINVAL.