1GPG-CONNECT-AGENT(1) GNU Privacy Guard GPG-CONNECT-AGENT(1)
2
6 gpg-connect-agent - Communicate with a running agent
7
9 gpg-connect-agent [options][commands]
10
13 The gpg-connect-agent is a utility to communicate with a running gpg-
14 agent. It is useful to check out the commands gpg-agent provides using
15 the Assuan interface. It might also be useful for scripting simple
16 applications. Input is expected at stdin and out put gets printed to
17 stdout.
18 It is very similar to running gpg-agent in server mode; but here we
20 connect to a running instance.
21 The following options may be used:
26 -v
29 --verbose
31 Output additional information while running.
32 -q
35 --quiet
37 Try to be as quiet as possible.
38 --homedir dir
41 Set the name of the home directory to dir. If this option is not
42 used, the home directory defaults to ‘~/.gnupg’. It is only
43 recognized when given on the command line. It also overrides
44 any home directory stated through the environment variable
45 ‘GNUPGHOME’ or (on W32 systems) by means of the Registry entry
46 HKCU\Software\GNU\GnuPG:HomeDir.
47 -S
51 --raw-socket name
53 Connect to socket name assuming this is an Assuan style server.
54 Do not run any special initializations or environment checks.
55 This may be used to directly connect to any Assuan style socket
56 server.
57 -E
60 --exec Take the rest of the command line as a program and it's argu‐
62 ments and execute it as an assuan server. Here is how you would
63 run gpgsm:
64 gpg-connect-agent --exec gpgsm --server
65 Note that you may not use options on the command line in this case.
66 --no-ext-connect
69 When using -S or --exec, gpg-connect-agent connects to the
70 assuan server in extended mode to allow descriptor passing.
71 This option makes it use the old mode.
72 --run file
75 Run the commands from file at startup and then continue with the
76 regular input method. Note, that commands given on the command
77 line are executed after this file.
78 -s
81 --subst
83 Run the command /subst at startup.
84 --hex Print data lines in a hex format and the ASCII representation of
87 non-control characters.
88 --decode
91 Decode data lines. That is to remove percent escapes but make
92 sure that a new line always starts with a D and a space.
93
97 While reading Assuan commands, gpg-agent also allows a few special com‐
98 mands to control its operation. These control commands all start with
99 a slash (/).
100 /echo args
104 Just print args.
105 /let name value
108 Set the variable name to value. Variables are only substituted
109 on the input if the /subst has been used. Variables are refer‐
110 enced by prefixing the name with a dollar sign and optionally
111 include the name in curly braces. The rules for a valid name
112 are identically to those of the standard bourne shell. This is
113 not yet enforced but may be in the future. When used with curly
114 braces no leading or trailing white space is allowed.
115 If a variable is not found, it is searched in the environment
117 and if found copied to the table of variables.
118 Variable functions are available: The name of the function must
120 be followed by at least one space and the at least one argument.
121 The following functions are available:
122 get Return a value described by the argument. Available
125 arguments are:
126 cwd The current working directory.
129 homedir
131 The gnupg homedir.
132 sysconfdir
134 GnuPG's system configuration directory.
135 bindir GnuPG's binary directory.
137 libdir GnuPG's library directory.
139 libexecdir
141 GnuPG's library directory for executable files.
142 datadir
144 GnuPG's data directory.
145 serverpid
147 The PID of the current server. Command /serverpid
148 must have been given to return a useful value.
149 unescape args
152 Remove C-style escapes from args. Note that \0 and \x00
153 terminate the returned string implicitly. The string to
154 be converted are the entire arguments right behind the
155 delimiting space of the function name.
156 unpercent args
159 unpercent+ args
161 Remove percent style escaping from args. Note that %00
162 terminates the string implicitly. The string to be con‐
163 verted are the entire arguments right behind the delimit‐
164 ing space of the function name. unpercent+ also maps plus
165 signs to a spaces.
166 percent args
169 percent+ args
171 Escape the args using percent style escaping. Tabs,
172 formfeeds, linefeeds, carriage returns and colons are
173 escaped. percent+ also maps spaces to plus signs.
174 errcode arg
177 errsource arg
179 errstring arg
181 Assume arg is an integer and evaluate it using strtol.
182 Return the gpg-error error code, error source or a for‐
183 matted string with the error code and error source.
184 +
188 -
190 *
192 /
194 % Evaluate all arguments as long integers using strtol and
196 apply this operator. A division by zero yields an empty
197 string.
198 !
201 |
203 & Evaluate all arguments as long integers using strtol and
205 apply the logical oeprators NOT, OR or AND. The NOT
206 operator works on the last argument only.
207 /definq name var
213 Use content of the variable var for inquiries with name. name
214 may be an asterisk (*) to match any inquiry.
215 /definqfile name file
219 Use content of file for inquiries with name. name may be an
220 asterisk (*) to match any inquiry.
221 /definqprog name prog
224 Run prog for inquiries matching name and pass the entire line to
225 it as command line arguments.
226 /datafile name
229 Write all data lines from the server to the file name. The file
230 is opened for writing and created if it does not exists. An
231 existing file is first truncated to 0. The data written to the
232 file fully decoded. Using a single dash for name writes to std‐
233 out. The file is kept open until a new file is set using this
234 command or this command is used without an argument.
235 /showdef
238 Print all definitions
239 /cleardef
242 Delete all definitions
243 /sendfd file mode
246 Open file in mode (which needs to be a valid fopen mode string)
247 and send the file descriptor to the server. This is usually
248 followed by a command like INPUT FD to set the input source for
249 other commands.
250 /recvfd
253 Not yet implemented.
254 /open var file [mode]
257 Open file and assign the file descriptor to var. Warning: This
258 command is experimental and might change in future versions.
259 /close fd
262 Close the file descriptor fd. Warning: This command is experi‐
263 mental and might change in future versions.
264 /showopen
267 Show a list of open files.
268 /serverpid
271 Send the Assuan command GETINFO pid to the server and store the
272 returned PID for internal purposes.
273 /sleep Sleep for a second.
276 /hex
279 /nohex Same as the command line option --hex.
281 /decode
284 /nodecode
286 Same as the command line option --decode.
287 /subst
290 /nosubst
292 Enable and disable variable substitution. It defaults to dis‐
293 abled unless the command line option --subst has been used. If
294 /subst as been enabled once, leading whitespace is removed from
295 input lines which makes scripts easier to read.
296 /while condition
299 /end These commands provide a way for executing loops. All lines
301 between the while and the corresponding end are executed as long
302 as the evaluation of condition yields a non-zero value. The
303 evaluation is done by passing condition to the strtol function.
304 Example:
305 /subst
307 /let i 3
308 /while $i
309 /echo loop couter is $i
310 /let i ${- $i 1}
311 /end
312 /run file
316 Run commands from file.
317 /bye Terminate the connection and the program
320 /help Print a list of available control commands.
323
328 gpg-agent(1), scdaemon(1)
329 The full documentation for this tool is maintained as a Texinfo manual.
331 If GnuPG and the info program are properly installed at your site, the
332 command
333 info gnupg
335 should give you access to the complete manual including a menu struc‐
337 ture and an index.
338GnuPG 2.0.14 2018-07-13 GPG-CONNECT-AGENT(1)