GFileMonitor: GIO Reference Manual

## GFileMonitor GFileMonitor — File Monitor |

## Functions

gboolean | g_file_monitor_cancel ()
gboolean | g_file_monitor_is_cancelled ()
void | g_file_monitor_set_rate_limit ()
void | g_file_monitor_emit_event ()

## Properties

gboolean | cancelled | Read
gint | rate-limit | Read / Write

## Signals

void | changed | Run Last

## Types and Values

enum | GFileMonitorEvent
| GFileMonitor

## Object Hierarchy

        GObject
        ╰── GFileMonitor

## Includes

    #include <gio/gio.h>

## Description

Monitors a file or directory for changes.

To obtain a GFileMonitor for a file or directory, use `g_file_monitor()`, `g_file_monitor_file()`, or `g_file_monitor_directory()`.

To get informed about changes to the file or directory you are monitoring, connect to the “changed” signal. The signal will be emitted in the thread-default main context of the thread that the monitor was created in (though if the global default main context is blocked, this may cause notifications to be blocked even if the thread-default context is still running).

## Functions

### g_file_monitor_cancel ()

    gboolean
    g_file_monitor_cancel (GFileMonitor *monitor);

Cancels a file monitor.

#### Parameters

monitor | a GFileMonitor. |

#### Returns

always `TRUE`

### g_file_monitor_is_cancelled ()

    gboolean
    g_file_monitor_is_cancelled (GFileMonitor *monitor);

Returns whether the monitor is canceled.

#### Parameters

monitor | a GFileMonitor |

#### Returns

`TRUE` if monitor is canceled. `FALSE` otherwise.

### g_file_monitor_set_rate_limit ()

    void
    g_file_monitor_set_rate_limit (GFileMonitor *monitor,
                                   gint limit_msecs);

Sets the rate limit to which the `monitor` will report consecutive change events to the same file.

#### Parameters

monitor | a GFileMonitor. |
limit_msecs | a non-negative integer with the limit in milliseconds to poll for changes |

### g_file_monitor_emit_event ()

    void
    g_file_monitor_emit_event (GFileMonitor *monitor,
                               GFile *child,
                               GFile *other_file,
                               GFileMonitorEvent event_type);

Emits the “changed” signal if a change has taken place. Should be called from file monitor implementations only.

Implementations are responsible to call this method from the thread-default main context of the thread that the monitor was created in.

#### Parameters

monitor | a GFileMonitor. |
child | a GFile. |
other_file | a GFile. |
event_type | a set of GFileMonitorEvent flags. |

## Types and Values

### enum GFileMonitorEvent

Specifies what type of event a monitor event is.

#### Members

G_FILE_MONITOR_EVENT_CHANGED | a file changed. |
G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT | a hint that this was probably the last change in a set of changes. |
G_FILE_MONITOR_EVENT_DELETED | a file was deleted. |
G_FILE_MONITOR_EVENT_CREATED | a file was created. |
G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED | a file attribute was changed. |
G_FILE_MONITOR_EVENT_PRE_UNMOUNT | the file location will soon be unmounted. |
G_FILE_MONITOR_EVENT_UNMOUNTED | the file location was unmounted. |
G_FILE_MONITOR_EVENT_MOVED | the file was moved -- only sent if the (deprecated) `G_FILE_MONITOR_SEND_MOVED` flag is set |
G_FILE_MONITOR_EVENT_RENAMED | the file was renamed within the current directory -- only sent if the `G_FILE_MONITOR_WATCH_MOVES` flag is set. Since: 2.46. |
G_FILE_MONITOR_EVENT_MOVED_IN | the file was moved into the monitored directory from another location -- only sent if the `G_FILE_MONITOR_WATCH_MOVES` flag is set. Since: 2.46. |
G_FILE_MONITOR_EVENT_MOVED_OUT | the file was moved out of the monitored directory to another location -- only sent if the `G_FILE_MONITOR_WATCH_MOVES` flag is set. Since: 2.46 |

### GFileMonitor

    typedef struct _GFileMonitor GFileMonitor;

Watches for changes to a file.

## Property Details

### The `“cancelled”` property

      “cancelled”                gboolean

Whether the monitor has been cancelled.

Flags: Read

Default value: FALSE

### The `“rate-limit”` property

      “rate-limit”               gint

The limit of the monitor to watch for changes, in milliseconds.

Flags: Read / Write

Allowed values: >= 0

Default value: 800

## Signal Details

### The `“changed”` signal

    void
    user_function (GFileMonitor     *monitor,
                   GFile            *file,
                   GFile            *other_file,
                   GFileMonitorEvent event_type,
                   gpointer          user_data)

Emitted when `file` has been changed.

If using `G_FILE_MONITOR_WATCH_MOVES` on a directory monitor, and the information is available (and if supported by the backend), `event_type` may be `G_FILE_MONITOR_EVENT_RENAMED`, `G_FILE_MONITOR_EVENT_MOVED_IN` or `G_FILE_MONITOR_EVENT_MOVED_OUT`.

In all cases `file` will be a child of the monitored directory. For renames, `file` will be the old name and `other_file` is the new name. For "moved in" events, `file` is the name of the file that appeared and `other_file` is the old name that it was moved from (in another directory). For "moved out" events, `file` is the name of the file that used to be in this directory and `other_file` is the name of the file at its new location.

It makes sense to treat `G_FILE_MONITOR_EVENT_MOVED_IN` as equivalent to `G_FILE_MONITOR_EVENT_CREATED` and `G_FILE_MONITOR_EVENT_MOVED_OUT` as equivalent to `G_FILE_MONITOR_EVENT_DELETED`, with extra information. `G_FILE_MONITOR_EVENT_RENAMED` is equivalent to a delete/create pair. This is exactly how the events will be reported in the case that the `G_FILE_MONITOR_WATCH_MOVES` flag is not in use.

If using the deprecated flag `G_FILE_MONITOR_SEND_MOVED` flag and `event_type` is G_FILE_MONITOR_EVENT_MOVED, `file` will be set to a GFile containing the old path, and `other_file` will be set to a GFile containing the new path.

In all the other cases, `other_file` will be set to NULL.

#### Parameters

monitor | a GFileMonitor. |
file | a GFile. |
other_file | a GFile or NULL. | [nullable]
event_type | a GFileMonitorEvent. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last