# ioctl_xfs_getparents

## NAME



           ioctl_xfs_getparents - query XFS directory parent information
    


## SYNOPSIS



           **#include <xfs/xfs_fs.h>**
    
           **int ioctl(int** _fd_**, XFS_IOC_GETPARENTS, struct xfs_getparents ***_arg_**);**
    
           **int ioctl(int** _fd_**, XFS_IOC_GETPARENTS_BY_HANDLE, struct**
           **xfs_getparents_by_handle ***_arg_**);**
    


## DESCRIPTION



           This command is used to retrieve the directory parent pointers of
           either the currently opened file or a file handle.  Parent
           pointers point upwards in the directory tree from a child file
           towards a parent directories.  Each entry in a parent directory
           must have a corresponding parent pointer in the child.
    
           Calling programs should allocate a large memory buffer and
           initialize a header of the following form:
    
               struct xfs_getparents {
                    struct xfs_attrlist_cursor  gp_cursor;
                    __u16                       gp_iflags;
                    __u16                       gp_oflags;
                    __u32                       gp_bufsize;
                    __u64                       __pad;
                    __u64                       gp_buffer;
               };
    
               struct xfs_getparents {
                    struct xfs_handle           gph_handle;
                    struct xfs_getparents       gph_request;
               };
    
           The field _gp_cursor_ tracks the progress of iterating through the
           parent pointers.  Calling programs must initialize this to zero
           before the first system call and must not touch it after that.
    
           The field _gp_iflags_ control the behavior of the query operation
           and provide more information about the outcome of the operation.
           There are no input flags currently defined; this field must be
           zero.
    
           The field _gp_oflags_ contains information about the query itself.
           Possibly output flags are:
    
               **XFS_GETPARENTS_OFLAG_ROOT**
                      The file queried was the root directory.
    
               **XFS_GETPARENTS_OFLAG_DONE**
                      There are no more parent pointers to query.
    
           The field ___pad_ must be zero.
    
           The field _gp_bufsize_ should be set to the size of the buffer, in
           bytes.
    
           The field _gp_buffer_ should point to an output buffer for the
           parent pointer records.
    
           Parent pointer records are returned in the following form:
    
               struct xfs_getparents_rec {
                    struct xfs_handle           gpr_parent;
                    __u16                       gpr_reclen;
                    char                        gpr_name[];
               };
    
           The field _gpr_parent_ is a file handle that can be used to open the
           parent directory.
    
           The field _gpr_reclen_ will be set to the number of bytes used by
           this parent record.
    
           The array _gpr_name_ will be set to a NULL-terminated byte sequence
           representing the filename stored in the parent pointer.  If the
           name is a zero-length string, the file queried has no parents.
    


## SAMPLE PROGRAM



           Calling programs should allocate a large memory buffer, initialize
           the head structure to zeroes, set gp_bufsize to the size of the
           buffer, and call the ioctl.  The XFS_GETPARENTS_OFLAG_DONE flag
           will be set in gp_flags when there are no more parent pointers to
           be read.  The below code is an example of XFS_IOC_GETPARENTS
           usage:
    
           #include <stdio.h>
           #include <string.h>
           #include <errno.h>
           #include <xfs/linux.h>
           #include <xfs/xfs.h>
           #include <xfs/xfs_types.h>
           #include <xfs/xfs_fs.h>
    
           int main() {
                struct xfs_getparents gp = { };
                struct xfs_getparents_rec *gpr;
                int error, fd;
    
                gp.gp_buffer = (uintptr_t)malloc(65536);
                if (!gp.gp_buffer) {
                     perror("malloc");
                     return 1;
                }
                gp->gp_bufsize = 65536;
    
                fd = open("/mnt/test/foo.txt", O_RDONLY | O_CREAT);
                if (fd  == -1)
                     return errno;
    
                do {
                     error = ioctl(fd, XFS_IOC_GETPARENTS, gp);
                     if (error)
                          return error;
    
                     for (gpr = xfs_getparents_first_rec(&gp);
                          gpr != NULL;
                          gpr = xfs_getparents_next_rec(&gp, gpr)) {
                          if (gpr->gpr_name[0] == 0)
                               break;
    
                          printf("inode       = %llu\n",
                                    gpr->gpr_parent.ha_fid.fid_ino);
                          printf("generation  = %u\n",
                                    gpr->gpr_parent.ha_fid.fid_gen);
                          printf("name        = \"%s\"\n\n",
                                    gpr->gpr_name);
                     }
                } while (!(gp.gp_flags & XFS_GETPARENTS_OFLAG_DONE));
    
                return 0;
           }
    


## RETURN VALUE



           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## ERRORS



           Error codes can be one of, but are not limited to, the following:
    
           **EFSBADCRC**
                  Metadata checksum validation failed while performing the
                  query.
    
           **EFSCORRUPTED**
                  Metadata corruption was encountered while performing the
                  query.
    
           **EINVAL** One or more of the arguments specified is invalid.
    
           **EMSGSIZE**
                  The record buffer was not large enough to store even a
                  single record.
    
           **ENOMEM** Not enough memory to retrieve parent pointers.
    
           **EOPNOTSUPP**
                  Repairs of the requested metadata object are not supported.
    
           **EROFS** Filesystem is read-only and a repair was requested.
    
           **ESHUTDOWN**
                  Filesystem is shut down due to previous errors.
    
           **EIO** An I/O error was encountered while performing the query.
    


## CONFORMING TO



           This API is specific to XFS filesystem on the Linux kernel.
    


* * *