IOCTL-XFS-GETPARENTS(2) System Calls Manual IOCTL-XFS-GETPARENTS(2)

# [NAME](#NAME)

ioctl\_xfs\_getparents - query XFS directory parent information

# [SYNOPSIS](#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](#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**](#XFS_GETPARENTS_OFLAG_ROOT)

The file queried was the root directory.

[**XFS\_GETPARENTS\_OFLAG\_DONE**](#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](#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](#RETURN_VALUE)

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

# [ERRORS](#ERRORS)

Error codes can be one of, but are not limited to, the following:

[**EFSBADCRC**](#EFSBADCRC)

Metadata checksum validation failed while performing the query.

[**EFSCORRUPTED**](#EFSCORRUPTED)

Metadata corruption was encountered while performing the query.

[**EINVAL**](#EINVAL)

One or more of the arguments specified is invalid.

[**EMSGSIZE**](#EMSGSIZE)

The record buffer was not large enough to store even a single record.

[**ENOMEM**](#ENOMEM)

Not enough memory to retrieve parent pointers.

[**EOPNOTSUPP**](#EOPNOTSUPP)

Repairs of the requested metadata object are not supported.

[**EROFS**](#EROFS)

Filesystem is read-only and a repair was requested.

[**ESHUTDOWN**](#ESHUTDOWN)

Filesystem is shut down due to previous errors.

[**EIO**](#EIO)

An I/O error was encountered while performing the query.

# [CONFORMING TO](#CONFORMING_TO)

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

# [SEE ALSO](#SEE_ALSO)

[**ioctl**(2)](/man/os/xfsprogs/ioctl.2)

2024-04-09 XFS

---

Document: ioctl_xfs_getparents(2) from xfsprogs 7.2.0-r0 (Chainguard OS)
Source: https://kernel.googlesource.com/pub/scm/fs/xfs/xfsprogs-dev