# `BEAMNotify`
[🔗](https://github.com/nerves-networking/beam_notify/blob/v1.1.1/lib/beam_notify.ex#L1)

Send a message to the BEAM from a shell script

# `dispatcher`

```elixir
@type dispatcher() :: ([String.t()], %{required(String.t()) => String.t()} -> :ok)
```

Callback for dispatching notifications

BEAMNotify calls the dispatcher function whenever a message comes in. The
first parameter is the list of arguments passed to `$BEAM_NOTIFY`. The
second argument is a map containing environment variables. Whether or
not the map is populated depends on the options to `start_link/1`.

# `options`

```elixir
@type options() :: [
  name: binary() | atom(),
  path: Path.t(),
  mode: non_neg_integer(),
  dispatcher: dispatcher(),
  report_env: boolean(),
  recbuf: non_neg_integer()
]
```

BEAMNotify takes the following options

* `:name` - a unique name for this notifier. This is required if you expect
  to run multiple BEAMNotify GenServers at a time.
* `:dispatcher` - a function to call when a notification comes in
* `:path` - the path to use for the named socket. A path in the system
   temporary directory is the default.
* `:mode` - the permissions to apply to the socket. Should be an octal number
   eg: 0o660 for read/write owner/group, no access to everyone else
* `:report_env` - set to `true` to report environment variables in addition
   to commandline argument. Defaults to `false`
* `:recbuf` - receive buffer size. If you're sending a particular large
   amount of data and getting errors from `:erlang.binary_to_term(data)`, try
   making this bigger. Defaults to 8192.

# `bin_path`

```elixir
@spec bin_path() :: Path.t()
```

Return the path to `beam_notify`

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `env`

```elixir
@spec env(pid() | binary() | atom() | keyword()) :: Enumerable.t()
```

Return the OS environment needed to call `$BEAM_NOTIFY`

This returns a map that can be passed directly to `System.cmd/3` via its
`:env` option.

This function can be passed different things based on what's convenient.

1. If you're setting up `child_spec`'s for a supervision tree and need the
   environment to pass in another `child_spec`, call this with the same
   options that you'd pass to `start_link/1`. This is a very common use.

2. If you called `start_link/1` manually and have the pid, call it with
   the pid.

3. If you only have the name that was passed to `start_link/1`, then call
   it with the name. The name alone is insufficient for returning the
   `$BEAM_NOTIFY_OPTIONS` environment variable, so the `BEAMNotify`
   GenServer must be running. If you're in a chicken-and-egg situation
   where you're setting up a supervision tree, but it hasn't been started
   yet, see option 1.

# `start_link`

```elixir
@spec start_link(options()) :: GenServer.on_start()
```

Start the BEAMNotify message receiver

---

*Consult [api-reference.md](api-reference.md) for complete listing*