Provides functions and constants for monitoring changes to a node. More...

Macros
#define	B_ATTR_CHANGED 5
	`B_NODE_MONITOR` notification message "opcode" set when attribute changes.

#define	B_ATTR_CREATED 1
	`B_ATTR_CHANGED` notification message "cause" set when attribute is created.

#define	B_ATTR_REMOVED 2
	`B_ATTR_CHANGED` notification message "cause" set when attribute is removed.

#define	B_DEVICE_MOUNTED 6
	`B_NODE_MONITOR` notification message "opcode" set when device is mounted.

#define	B_DEVICE_UNMOUNTED 7
	`B_NODE_MONITOR` notification message "opcode" set when device is unmounted.

#define	B_ENTRY_CREATED 1
	`B_NODE_MONITOR` notification message "opcode" is set when entry is created.

#define	B_ENTRY_MOVED 3
	`B_NODE_MONITOR` notification message "opcode" is set when entry is moved.

#define	B_ENTRY_REMOVED 2
	`B_NODE_MONITOR` notification message "opcode" is set when entry is removed.

#define	B_STAT_CHANGED 4
	`B_NODE_MONITOR` notification message "opcode" set when stat info changes.

Enumerations
enum	{ B_STOP_WATCHING = 0x0000 , B_WATCH_NAME = 0x0001 , B_WATCH_STAT = 0x0002 , B_WATCH_ATTR = 0x0004 , B_WATCH_DIRECTORY = 0x0008 , B_WATCH_ALL = 0x000f , B_WATCH_MOUNT = 0x0010 , B_WATCH_INTERIM_STAT = 0x0020 , B_WATCH_CHILDREN = 0x0040 }

enum	{ B_STAT_MODE = 0x0001 , B_STAT_UID = 0x0002 , B_STAT_GID = 0x0004 , B_STAT_SIZE = 0x0008 , B_STAT_ACCESS_TIME = 0x0010 , B_STAT_MODIFICATION_TIME = 0x0020 , B_STAT_CREATION_TIME = 0x0040 , B_STAT_CHANGE_TIME = 0x0080 , B_STAT_INTERIM_UPDATE = 0x1000 }

Functions
status_t	stop_watching (BMessenger target)
	Unsubscribes target from node and mount monitoring.

status_t	stop_watching (const BHandler handler, const BLooper looper=NULL)
	Unsubscribes handler or looper target from node and mount monitoring.

status_t	watch_node (const node_ref *node, uint32 flags, BMessenger target)
	Subscribes or unsubscribes target to node and/or mount watching.

status_t	watch_node (const node_ref node, uint32 flags, const BHandler handler, const BLooper *looper=NULL)
	Subscribes or unsubscribes handler or looper to node and/or mount watching.

status_t	watch_volume (dev_t volume, uint32 flags, BMessenger target)
	Subscribes target to watch node changes on volume.

status_t	watch_volume (dev_t volume, uint32 flags, const BHandler handler, const BLooper looper=NULL)
	Subscribes handler or looper to watch node changes on volume.

Detailed Description

Provides functions and constants for monitoring changes to a node.

The are three main node monitoring functions are watch_volume(), watch_node(), and stop_watching().

watch_volume() starts watching a volume and sends a message when a requested event occurs.
watch_node() starts or stops watching a node, or watches for volumes to be mounted and unmounted, and sends a message when an event occurs.
stop_watching() stops monitoring a node or volume and no longer sends messages.

Macro Definition Documentation

◆ B_ATTR_CHANGED

#define B_ATTR_CHANGED 5

B_NODE_MONITOR notification message "opcode" set when attribute changes.

More information can be found in the "cause" field.

Since: BeOS R3

◆ B_ATTR_CREATED

#define B_ATTR_CREATED 1

B_ATTR_CHANGED notification message "cause" set when attribute is created.

Since: Haiku R1

◆ B_ATTR_REMOVED

#define B_ATTR_REMOVED 2

B_ATTR_CHANGED notification message "cause" set when attribute is removed.

Since: Haiku R1

◆ B_DEVICE_MOUNTED

#define B_DEVICE_MOUNTED 6

B_NODE_MONITOR notification message "opcode" set when device is mounted.

Since: BeOS R3

◆ B_DEVICE_UNMOUNTED

#define B_DEVICE_UNMOUNTED 7

B_NODE_MONITOR notification message "opcode" set when device is unmounted.

Since: BeOS R3

◆ B_ENTRY_CREATED

#define B_ENTRY_CREATED 1

B_NODE_MONITOR notification message "opcode" is set when entry is created.

Since: BeOS R3

◆ B_ENTRY_MOVED

#define B_ENTRY_MOVED 3

B_NODE_MONITOR notification message "opcode" is set when entry is moved.

Since: BeOS R3

◆ B_ENTRY_REMOVED

#define B_ENTRY_REMOVED 2

B_NODE_MONITOR notification message "opcode" is set when entry is removed.

Since: BeOS R3

◆ B_STAT_CHANGED

#define B_STAT_CHANGED 4

B_NODE_MONITOR notification message "opcode" set when stat info changes.

More information can be found in the "fields" field.

Since: BeOS R3

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
B_STOP_WATCHING	Unsubscribe from watching a node. Flag for watch_node(). Attention `B_STOP_WATCHING` does not apply to volume watching, you must call stop_watching() instead. Since BeOS R3
B_WATCH_NAME	Subscribe to watching for change to the name of a node. Flag for watch_volume() and watch_node(). Since BeOS R3
B_WATCH_STAT	Subscribe to watching for changes to the stat information of a node. Flag for watch_volume() and watch_node(). Since BeOS R3
B_WATCH_ATTR	Subscribe to watching for changes to the attributes of a node. Flag for watch_volume() and watch_node(). Since BeOS R3
B_WATCH_DIRECTORY	Subscribe to watching for changes to the contents of a directory. Flag for watch_node(). Since BeOS R3
B_WATCH_ALL	Flag for watch_node(). Subscribe to watching for changes to all information of a node except `B_WATCH_MOUNT`. Since BeOS R3
B_WATCH_MOUNT	Subscribe to watching for when a volume is mounted or unmounted. You may prefer to use BVolumeRoster for volume watching instead. Flag for watch_node(). Since BeOS R3
B_WATCH_INTERIM_STAT	To avoid a flood of messages for small and frequent write operations on an open file the file system can limit the number of notifications and mark them with the `B_WATCH_INTERIM_STAT` flag.

◆ anonymous enum

anonymous enum

Enumerator
B_STAT_MODE	Set when stat mode changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_UID	Set when UID changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_GID	Set when GID changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_SIZE	Set when stat size changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_ACCESS_TIME	Set when access time changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_MODIFICATION_TIME	Set when modification time changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_CREATION_TIME	Set when creation time changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_CHANGE_TIME	Set when access, modification or creation time changes. `B_STAT_CHANGED` notification messages "fields" flag. Since Haiku R1
B_STAT_INTERIM_UPDATE	Set when file is written to.

Function Documentation

◆ stop_watching() [1/2]

status_t stop_watching ( BMessenger target )

Unsubscribes target from node and mount monitoring.

You may still receive notification messages after calling stop_watching() because while node monitoring is asynchronous and all changes are atomic, message sending is not atomic so there is a lag time from when you stop monitoring and when the message is received in your message receiving thread. You can check the timestamp of the message to determine if it was sent after stop_watching() was called.

Parameters

target BMessenger object referring to the target.

Returns: A status code.

Return values

B_OK	Stopped sending notification messages to the target.
B_BAD_VALUE	target was invalid.
B_ENTRY_NOT_FOUND	Node not found.

Since: BeOS R3

◆ stop_watching() [2/2]

status_t stop_watching	(	const BHandler *	handler,
		const BLooper *	looper = `NULL`
	)

Unsubscribes handler or looper target from node and mount monitoring.

You may still receive notification messages after calling stop_watching() because while node monitoring is asynchronous and all changes are atomic, message sending is not atomic so there is a lag time from when you stop monitoring and when the message is received in your message receiving thread. You can check the timestamp of the message to determine if it was sent after stop_watching() was called.

Parameters

handler	The target handler, may be `NULL`. If looper is not `NULL` then the looper's preferred handler is targeted.
looper	The target looper, may be `NULL`. If handler is not `NULL` then the handler's looper is targeted.

Returns: A status code.

Return values

B_OK	Stopped sending notification messages to the target.
B_BAD_VALUE	Target from handler or looper was invalid.
B_ENTRY_NOT_FOUND	Node not found.

Since: BeOS R3

◆ watch_node() [1/2]

status_t watch_node	(	const node_ref *	node,
		uint32	flags,
		BMessenger	target
	)

Subscribes or unsubscribes target to node and/or mount watching.

Depending of flags the action performed by this function varies:

flags is 0: The target is unsubscribed from watching the node. node must not be NULL in this case.
flags contains B_WATCH_MOUNT: The target is subscribed to mount watching.
flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, B_WATCH_ATTR, or B_WATCH_DIRECTORY: The target is subscribed to watching the specified aspects of the node. node must not be NULL in this case.

flags may include:

B_STOP_WATCHING

or one or more of the following:

B_WATCH_NAME
B_WATCH_STAT
B_WATCH_ATTR
B_WATCH_DIRECTORY
B_WATCH_ALL
B_WATCH_MOUNT

Note that the latter two cases are not mutual exclusive, i.e. mount and node watching can be requested with a single call.

Parameters

node	node_ref referring to the node to be watched. May be `NULL`, if only mount watching is requested.
flags	Flags indicating the actions to be performed.
target	BMessenger object referring to the target.

Returns: B_OK if everything went fine, an error code otherwise.

Since: BeOS R3

◆ watch_node() [2/2]

status_t watch_node	(	const node_ref *	node,
		uint32	flags,
		const BHandler *	handler,
		const BLooper *	looper = `NULL`
	)

Subscribes or unsubscribes handler or looper to node and/or mount watching.

Depending of flags the action performed by this function varies:

flags is 0: The target is unsubscribed from watching the node. node must not be NULL in this case.
flags contains B_WATCH_MOUNT: The target is subscribed to mount watching.
flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, B_WATCH_ATTR, or B_WATCH_DIRECTORY: The target is subscribed to watching the specified aspects of the node. node must not be NULL in this case.

flags may include:

B_STOP_WATCHING

or one or more of the following:

B_WATCH_NAME
B_WATCH_STAT
B_WATCH_ATTR
B_WATCH_DIRECTORY
B_WATCH_ALL
B_WATCH_MOUNT

Note that the latter two cases are not mutual exclusive, i.e. mount and node watching can be requested with a single call.

Parameters

node	node_ref referring to the node to be watched. May be `NULL`, if only mount watching is requested.
flags	Flags indicating the actions to be performed.
handler	The target handler. May be `NULL`, if looper is not `NULL`. Then the preferred handler of the looper is targeted.
looper	The target looper. May be `NULL`, if handler is not `NULL`. Then the handler's looper is the target looper.

Returns: B_OK if everything went fine, an error code otherwise.

Since: BeOS R3

◆ watch_volume() [1/2]

status_t watch_volume	(	dev_t	volume,
		uint32	flags,
		BMessenger	target
	)

Subscribes target to watch node changes on volume.

Depending of flags the action performed by this function varies:

flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR: The target is subscribed to watching the specified aspects of any node on the volume.

flags may include:

B_WATCH_NAME
B_WATCH_STAT
B_WATCH_ATTR

B_WATCH_VOLUME flag is assumed.

Parameters

volume	dev_t referring to the volume to be watched.
flags	Flags indicating the actions to be performed.
target	Messenger referring to the target. Must be valid.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	flags did not include one of `B_WATCH_NAME`, `B_WATCH_STAT`, or `B_WATCH_ATTR`.

Since: Haiku R1

◆ watch_volume() [2/2]

status_t watch_volume	(	dev_t	volume,
		uint32	flags,
		const BHandler *	handler,
		const BLooper *	looper = `NULL`
	)

Subscribes handler or looper to watch node changes on volume.

Depending of flags the action performed by this function varies:

flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR: The target is subscribed to watching the specified aspects of any node on the volume.

flags may include:

B_WATCH_NAME
B_WATCH_STAT
B_WATCH_ATTR

B_WATCH_VOLUME flag is assumed.

Parameters

volume	dev_t referring to the volume to be watched.
flags	Flags indicating the actions to be performed.
handler	The target handler. May be `NULL`, if looper is not `NULL`. Then the preferred handler of the looper is targeted.
looper	The target looper. May be `NULL`, if handler is not `NULL`. Then the handler's looper is the target looper.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	flags did not include one of `B_WATCH_NAME`, `B_WATCH_STAT`, or `B_WATCH_ATTR`.

Since: Haiku R1

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ B_ATTR_CHANGED

◆ B_ATTR_CREATED

◆ B_ATTR_REMOVED

◆ B_DEVICE_MOUNTED

◆ B_DEVICE_UNMOUNTED

◆ B_ENTRY_CREATED

◆ B_ENTRY_MOVED

◆ B_ENTRY_REMOVED

◆ B_STAT_CHANGED

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ stop_watching() [1/2]

◆ stop_watching() [2/2]

◆ watch_node() [1/2]

◆ watch_node() [2/2]

◆ watch_volume() [1/2]

◆ watch_volume() [2/2]