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 --agent-program file
51 Specify the agent program to be started if none is running.
52 -S
56 --raw-socket name
58 Connect to socket name assuming this is an Assuan style server.
59 Do not run any special initializations or environment checks.
60 This may be used to directly connect to any Assuan style socket
61 server.
62 -E
65 --exec Take the rest of the command line as a program and it's argu‐
67 ments and execute it as an assuan server. Here is how you would
68 run gpgsm:
69 gpg-connect-agent --exec gpgsm --server
70 Note that you may not use options on the command line in this case.
71 --no-ext-connect
74 When using -S or --exec, gpg-connect-agent connects to the
75 assuan server in extended mode to allow descriptor passing.
76 This option makes it use the old mode.
77 --run file
80 Run the commands from file at startup and then continue with the
81 regular input method. Note, that commands given on the command
82 line are executed after this file.
83 -s
86 --subst
88 Run the command /subst at startup.
89 --hex Print data lines in a hex format and the ASCII representation of
92 non-control characters.
93 --decode
96 Decode data lines. That is to remove percent escapes but make
97 sure that a new line always starts with a D and a space.
98
102 While reading Assuan commands, gpg-agent also allows a few special com‐
103 mands to control its operation. These control commands all start with
104 a slash (/).
105 /echo args
109 Just print args.
110 /let name value
113 Set the variable name to value. Variables are only substituted
114 on the input if the /subst has been used. Variables are refer‐
115 enced by prefixing the name with a dollar sign and optionally
116 include the name in curly braces. The rules for a valid name
117 are identically to those of the standard bourne shell. This is
118 not yet enforced but may be in the future. When used with curly
119 braces no leading or trailing white space is allowed.
120 If a variable is not found, it is searched in the environment
122 and if found copied to the table of variables.
123 Variable functions are available: The name of the function must
125 be followed by at least one space and the at least one argument.
126 The following functions are available:
127 get Return a value described by the argument. Available
130 arguments are:
131 cwd The current working directory.
134 homedir
136 The gnupg homedir.
137 sysconfdir
139 GnuPG's system configuration directory.
140 bindir GnuPG's binary directory.
142 libdir GnuPG's library directory.
144 libexecdir
146 GnuPG's library directory for executable files.
147 datadir
149 GnuPG's data directory.
150 serverpid
152 The PID of the current server. Command /serverpid
153 must have been given to return a useful value.
154 unescape args
157 Remove C-style escapes from args. Note that \0 and \x00
158 terminate the returned string implicitly. The string to
159 be converted are the entire arguments right behind the
160 delimiting space of the function name.
161 unpercent args
164 unpercent+ args
166 Remove percent style escaping from args. Note that %00
167 terminates the string implicitly. The string to be con‐
168 verted are the entire arguments right behind the delimit‐
169 ing space of the function name. unpercent+ also maps plus
170 signs to a spaces.
171 percent args
174 percent+ args
176 Escape the args using percent style escaping. Tabs,
177 formfeeds, linefeeds, carriage returns and colons are
178 escaped. percent+ also maps spaces to plus signs.
179 errcode arg
182 errsource arg
184 errstring arg
186 Assume arg is an integer and evaluate it using strtol.
187 Return the gpg-error error code, error source or a for‐
188 matted string with the error code and error source.
189 +
193 -
195 *
197 /
199 % Evaluate all arguments as long integers using strtol and
201 apply this operator. A division by zero yields an empty
202 string.
203 !
206 |
208 & Evaluate all arguments as long integers using strtol and
210 apply the logical oeprators NOT, OR or AND. The NOT
211 operator works on the last argument only.
212 /definq name var
218 Use content of the variable var for inquiries with name. name
219 may be an asterisk (*) to match any inquiry.
220 /definqfile name file
224 Use content of file for inquiries with name. name may be an
225 asterisk (*) to match any inquiry.
226 /definqprog name prog
229 Run prog for inquiries matching name and pass the entire line to
230 it as command line arguments.
231 /datafile name
234 Write all data lines from the server to the file name. The file
235 is opened for writing and created if it does not exists. An
236 existing file is first truncated to 0. The data written to the
237 file fully decoded. Using a single dash for name writes to std‐
238 out. The file is kept open until a new file is set using this
239 command or this command is used without an argument.
240 /showdef
243 Print all definitions
244 /cleardef
247 Delete all definitions
248 /sendfd file mode
251 Open file in mode (which needs to be a valid fopen mode string)
252 and send the file descriptor to the server. This is usually
253 followed by a command like INPUT FD to set the input source for
254 other commands.
255 /recvfd
258 Not yet implemented.
259 /open var file [mode]
262 Open file and assign the file descriptor to var. Warning: This
263 command is experimental and might change in future versions.
264 /close fd
267 Close the file descriptor fd. Warning: This command is experi‐
268 mental and might change in future versions.
269 /showopen
272 Show a list of open files.
273 /serverpid
276 Send the Assuan command GETINFO pid to the server and store the
277 returned PID for internal purposes.
278 /sleep Sleep for a second.
281 /hex
284 /nohex Same as the command line option --hex.
286 /decode
289 /nodecode
291 Same as the command line option --decode.
292 /subst
295 /nosubst
297 Enable and disable variable substitution. It defaults to dis‐
298 abled unless the command line option --subst has been used. If
299 /subst as been enabled once, leading whitespace is removed from
300 input lines which makes scripts easier to read.
301 /while condition
304 /end These commands provide a way for executing loops. All lines
306 between the while and the corresponding end are executed as long
307 as the evaluation of condition yields a non-zero value or is the
308 string true or yes. The evaluation is done by passing condition
309 to the strtol function. Example:
310 /subst
312 /let i 3
313 /while $i
314 /echo loop couter is $i
315 /let i ${- $i 1}
316 /end
317 /if condition
320 /end These commands provide a way for conditional execution. All
322 lines between the if and the corresponding end are executed only
323 if the evaluation of condition yields a non-zero value or is the
324 string true or yes. The evaluation is done by passing condition
325 to the strtol function.
326 /run file
329 Run commands from file.
330 /bye Terminate the connection and the program
333 /help Print a list of available control commands.
336
341 gpg-agent(1), scdaemon(1)
342 The full documentation for this tool is maintained as a Texinfo manual.
344 If GnuPG and the info program are properly installed at your site, the
345 command
346 info gnupg
348 should give you access to the complete manual including a menu struc‐
350 ture and an index.
351GnuPG 2.0.22 2018-07-13 GPG-CONNECT-AGENT(1)