---
name: "upstart-file-bridge"
section: "8"
platform: "linux"
package: "upstart"
version: "1.11-5"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/upstart-file-bridge"
---

# upstart-file-bridge(8)

Bridge between Upstart and inotify

## NAME

upstart-file-bridge - Bridge between Upstart and inotify

## SYNOPSIS

**upstart-file-bridge** \[*OPTIONS*\]...

## DESCRIPTION

**upstart-file-bridge** receives information about kernel file events that [**inotify**(7)](/inotify/7.md) has received and creates [**init**(8)](/init/8.md) events for them.

Supported events exposed to Upstart allow jobs to detect creation, modification and deletion. See [**file-event**(7)](/file-event/7.md) for further details.

The bridge works by querying the [**init**(8)](/init/8.md) daemon at bridge startup time to determine a list of all jobs whose **start on** or **stop on** conditions reference the **file** event. Further, the bridge arranges to be notified automatically when new jobs are created such that any subsequent jobs which reference the **file** event are also handled (as are job deletions).

See [**inotify**(7)](/inotify/7.md) and for further details.

## OPTIONS

- **--daemon**

  Detach and run in the background.

- **--debug**

  Enable debugging output.

- **--help**

  Show brief usage summary.

- **--user**

  User-session mode: connect to Upstart via the user session rather than over the D-Bus system bus.

- **--verbose**

  Enable verbose output.

## JOB ENVIRONMENT VARIABLES

- **FILE**

  Path to file to watch. When run without **--user**, this must be an absolute path. If **--user** is specified, certain relative path types are supported:

  - •

    If the path begins with '~/', the value will be expanded as would be performed by a shell for matching purposes (although when the event is emitted, the original value will be used).

  - •

    If the path begins with './', '.' will be assumed to be the users home directory.

  - •

    In all other scenarios, if the path does not begin with '/', it will be assumed to represent a file below the users home directory.

  If the path ends with a slash, it is considered to be a directory which changes the match behaviour (see below).

  If the path is not a directory, the file (but not the directory) portion of the path may contain wildcard matches. See [**fnmatch**(3)](/fnmatch/3.md) and [**glob**(7)](/glob/7.md) for further details.

- **EVENT**

  Event relating to **FILE** that job is interested in. If this variable is specified the value must be set to  **create**,  **modify** or  **delete** depending on what type of file event the job is interested in. If **FILE** is not specified, the bridge will watch for all types and set this variable to the appropriate value when emitting the event.

## WATCH TYPE BEHAVIOUR

The bridge emits events depending not only on the value of **EVENT**,  but also on the entity specified by **FILE**:

### File

An event will be emitted when the named file is created, modified or deleted depending on the value of **EVENT**. If **EVENT** is not specified, react to creation, modification and deletion.

If the file already exists when the job is registered, and **EVENT** either specifies *create* or the variable is not specified, the event will be emitted.

### Directory

An event will be emitted when the named directory is created, modified (files within it are created, modified or deleted) or deleted depending on the value of **EVENT**. If **EVENT** is not specified, react to creation, modification and deletion.

If the directory already exists when the job is registered, and **EVENT** either specifies *create* or the variable is not specified, the event will be emitted.

### Glob

One event will be emitted per match when the glob wildcard matches any files in the directory part is created, modified or deleted, depending on the value of **EVENT**. If **EVENT** is not specified, react to creation, modification and deletion.

If any matches already exist when the job is registered, and **EVENT** either specifies *create* or the variable is not specified, events will be emitted.

## NOTES

- •

  A single instance of the bridge may be run at the system level, but multiple further instances may be run per user session instance by using the **--user**.

- •

  All job conditions specifying the **file** event are multi-shot: if the same file event occurs multiple times, the bridge will emit an Upstart event each time.

## LIMITATIONS

- •

  Since the bridge currently uses  [**inotify**(7)](/inotify/7.md), it is subject to the same limitations; namely that recursive watches cannot be created reliably in all circumstances. As such, pathological scenarios such as deep directory trees being created and then quickly removed **cannot** be handled reliably. The following provides advice to minimise unexpected behaviour:

  - •

    Attempt to only watch for files to be created, modified or deleted in directories that are guaranteed to already exist at the time the job is registered by the bridge.

  - •

    If the system cannot guarantee that the directory will exist at job registration time, arrange for the directory to be created by an Upstart job before the bridge itself starts.

  - •

    In user session mode, if a job specifies a file to watch for and that file is created but inaccessible to the user running the bridge, no event will be emitted.

- •

  Tilde expansion is only supported for the current user; that is '~otheruser' will not work.

## AUTHOR

Written by James Hunt \<**james.hunt@canonical.com**\>

## BUGS

Report bugs at  \<**https://launchpad.net/ubuntu/+source/upstart/+bugs**\>

## COPYRIGHT

Copyright © 2013 Canonical Ltd.

This is free software; see the source for copying conditions.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO

[**init**(5)](/init/5.md) [**init**(8)](/init/8.md) [**inotify**(7)](/inotify/7.md) [**file-event**(7)](/file-event/7.md)