gpfs_add_watch subroutine

Watches the files in a folder specified by pathname.

Library

GPFS™ Library (libgpfswatch.so for Linux)

Synopsis

#include  <gpfs_watch.h>
int gpfs_add_watch (
         int pwd, 
         const char* pathname, 
         uint32_t event_mask)

Description

The gpfs_add_watch subroutine watches files in the folder specified by pathname. The watch is non-recursive like Linux inotify. This means that the contents in subfolders under the watched folder are not watched. The gpfs_add_watch subroutine registers your intention to watch said folder. In addition, it also verifies if the file system that you want to watch is owned by the local cluster. Currently, watches over file systems mounted on an accessing cluster are not supported.

Important: Given an IBM Spectrum Scale™ cluster, you can only set watches on it for file systems that the cluster owns. For instance, if cluster A mounts file system F whose owning cluster is cluster B, you can only watch F from cluster B, but not from cluster A.

For an overview of watch folder, see Introduction to watch folder.

Parameters

pwd: The parent watch descriptor that is returned by gpfs_init_watch. You can set up multiple child watches (folder, fileset, or inode space) under the same parent watch as long as they are watching the same file system.
pathname: The path of the folder that is being watched.
event_mask: One or more of the events that is described in Introduction to watch folder.

Exit status

The gpfs_add_watch subroutine returns the child watch descriptor (cwd) on success or -1 on failure.

Error status

Errno is set if -1 is returned.

EBADF: Invalid pwd was passed.
ENODEV: The path is not a mounted IBM Spectrum Scale file system.
EXDEV: The path belongs to a different file system.
ENOSYS: This cluster is not the owning cluster for this file system.
EINTR: Exceeded the number of watches allowed for a file system (25).
EDOM: The file system level needs to be upgraded. Watch folder is not supported.
EDESTADDRREQ: The message queue for this cluster is not ready. Enable the message queue before starting a watch.
ENODATA: Message queue error.
EHOSTUNREACH: Could not find the node name.

Note: Further errnos might be reported depending on the inner instrumentation of the API. Use gpfs_watch_strerror to learn more about an error.

Examples

For an example using gpfs_*_watch, see /usr/lpp/mmfs/samples/util/tswf.C.

Location

/usr/lpp/mmfs/lib/libgpfswatch.so for Linux