---
name: "ioctl_xfs_getparents"
section: "2"
platform: "linux"
package: "xfsprogs"
version: "7.2.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ioctl_xfs_getparents"
---

# ioctl\_xfs\_getparents(2)

query XFS directory parent information

## 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_by_handle {
	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.

## SEE ALSO

[**ioctl**(2)](/ioctl/2.md)