= gpsdctl(8)
:author: Eric S. Raymond
:date: 03 February 2026
:email: <esr@thyrsus.com.>
:keywords: gps, gpsdctl
:manmanual: GPSD Documentation
:mansource: GPSD, Version {gpsdver}
:robots: index,follow
:sectlinks:
:toc: macro
:type: manpage

include::../www/inc-menu.adoc[]

== NAME

gpsdctl - tool for sending commands to gpsd over its control socket

== SYNOPSIS

*gpsdctl* _action_ _device_

== OPTIONS

*-?*, *-h*, *--help*::
  Print a summary of options and then exit.
*-l*::
  Log to _stderr_, instead of *syslog*.
*-V*, *--version*::
  Print the package version and exit.

== ACTIONS

*action*:: may be _add_ or _remove_. If no daemon instance
is running when an _add_ is requested, this program will launch one.

*device*:: argument should be the pathname of a device. The device will
be opened by *gpsd* to read sensor data.  The device may not be a PPS
device. *gpsd* must open PPS devices on startup before dropping root.

== DESCRIPTION

This is a tool for sending an instance of *gpsd* commands over its control
socket to add or remove devices from the daemon's device list. It is not
intended to be called by users, but rather by the Linux hotplug system
and similar facilities

It should be run as root, unless *gpsd* was not started as root.  It can
fail in non-obvious ways when run with *sudo*.

It does not print errors, instead sending them to the syslog.

== ENVIRONMENT

Two environment variables are interpreted.

*GPSD_SOCKET*:: sets the location of the control socket. If the effective
user ID of this program is root then it usually defaults to
_/run/gpsd.sock_, although some systems may use the deprecated
_/var/run/gpsd.sock_ instead. Non-root users will use _/tmp/gpsd.sock_.

*GPSD_OPTIONS*:: may be a list of options to be passed to gpsd when this
tool launches it. It defaults to an empty string.

== RETURN VALUES

*0*:: on success.
*1*:: if the action was unknown or the write to the control socket failed,

== SEE ALSO

*gpsd*(8), *gpsctl*(1), *gps*(1), *libgps*(3), *libgpsmm*(3), *gpsprof*(1),
*gpsfake*(1), *syslog*(8).

== RESOURCES

*Project web site:* {gpsdweb}

== COPYING

This file is Copyright 2013 by the GPSD project +
SPDX-License-Identifier: BSD-2-clause
