# dbus/register-name Request a well-known bus name from the daemon (`RequestName`). A well-known name (`org.freedesktop.Notifications`, `org.deft.myapp`) is a bus-level alias that at most one connection owns at a time — callers address the name and the bus routes to whoever owns it. Every other connection can still call and subscribe; only ownership is exclusive. Custom names are the standard way for separate deft processes to address each other. ## Syntax 
[dbus/register-name $conn "org.example.X" ?flags]
## Parameters - `$conn` — connection from `dbus/connect` - `$name` — well-known name to own (string) - `$flags` — optional numeric `RequestName` flags (default `0`; a non-number is treated as `0`), a bitmask: | Flag | Value | Meaning | |---|---|---| | `ALLOW_REPLACEMENT` | `1` | Another requester with `REPLACE_EXISTING` may take the name from us | | `REPLACE_EXISTING` | `2` | Try to take the name from its current owner | | `DO_NOT_QUEUE` | `4` | If the name can't be acquired, return `3` instead of queueing | Replacement is mutual: `REPLACE_EXISTING` only succeeds when the current owner requested the name with `ALLOW_REPLACEMENT` (the CVE-2008-4311 hardening). A service that does not opt in cannot be displaced from the outside. | Flags | Behaviour | |---|---| | `0` | Classic service: first wins, latecomers queue silently | | `4` | Fail fast with `3` when busy — never queue | | `6` | Take over if allowed, otherwise `3` | | `7` | As `6`, plus allow a future daemon to replace us | Without `DO_NOT_QUEUE`, a busy name yields result `2`: the connection looks healthy but receives nothing until the incumbent exits. Services that consume a shared name (notification daemons, MPRIS players) should use `4`/`6`/`7` so "busy" is visible. ## Examples 
set rc [await [dbus/register-name $conn "org.deft.test"]]
# → 1  (primary owner)

# Take over from a permissive owner, otherwise fail fast:
set rc [await [dbus/register-name $conn "org.deft.test" 6]]

# Recommended for a long-lived daemon (replace + no-queue + allow-replace):
set rc [await [dbus/register-name $conn "org.deft.test" 7]]
On failure you can identify the incumbent via the bus object: 
set owner [await [dbus/call $conn "org.freedesktop.DBus" "/org/freedesktop/DBus" \
           "org.freedesktop.DBus" "GetNameOwner" "s" "org.freedesktop.Notifications"]]
set pid   [await [dbus/call $conn "org.freedesktop.DBus" "/org/freedesktop/DBus" \
           "org.freedesktop.DBus" "GetConnectionUnixProcessID" "s" $owner]]
## Returns Future resolving to the numeric result code: - `1` — primary owner - `2` — queued (another owner exists) - `3` — name exists and was not queued - `4` — already the owner `%Err` for a non-string name, a closed connection, or a daemon error. ## See Also `dbus/export`, `dbus/unique-name`, `dbus/call`
← dbus/info
dbus/send →