unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

GPG-CONNECT-AGENT(1)           GNU Privacy Guard          GPG-CONNECT-AGENT(1)



NAME
       gpg-connect-agent - Communicate with a running agent

SYNOPSIS
       gpg-connect-agent [options]


DESCRIPTION
       The  gpg-connect-agent  is a utility to communicate with a running gpg-
       agent.  It is useful to check out the commands gpg-agent provides using
       the  Assuan  interface.   It  might also be useful for scripting simple
       applications.  Inputis expected at stdin and out put  gets  printed  to
       stdout.

       It  is  very  similar  to running gpg-agent in server mode; but here we
       connect to a running instance.




       The following options may be used:


       -v

       --verbose
              Output additional information while running.


       -q

       --quiet
              Try to be as quiet as possible.


       --homedir dir
              Set the name of the home directory to dir. If his option is  not
              used,  the  home  directory  defaults to `~/.gnupg'.  It is only
              recognized when given on the command line.   It  also  overrides
              any  home  directory  stated  through  the  environment variable
              `GNUPGHOME' or (on W32 systems) by means on the  Registry  entry
              HKCU\Software\GNU\GnuPG:HomeDir.


       -S

       --raw-socket name
              Connect  to socket name assuming this is an Assuan style server.
              Do not run any special initializations  or  environment  checks.
              This  may be used to directly connect to any Assuan style socket
              server.


       -E

       --exec Take the rest of the command line as a program  and  it's  argu-
              ments  and execute it as an assuan server. Here is how you would
              run gpgsm:
          gpg-connect-agent --exec gpgsm --server



       --no-ext-connect
              When using -S  or  --exec,  gpg-connect-agent  connects  to  the
              assuan  server  in  extended  mode  to allow descriptor passing.
              This option makes it use the old mode.


       --run file
              Run the commands from file at startup and then continue with the
              regular input method.


       -s

       --subst
              Run the command /subst at startup.


       --hex  Print data lines in a hex format and the ASCII representation of
              non-control characters.


       --decode
              Decode data lines.  That is to remove percent escapes  but  make
              sure that a new line always starts with a D and a space.



CONTROL COMMANDS
       While reading Assuan commands, gpg-agent also allows a few special com-
       mands to control its operation.  These control commands all start  with
       a slash (/).



       /echo args
              Just print args.


       /let name value
              Set  the variable name to value.  Variables are only substituted
              on the input if the /subst has been used.  Variables are  refer-
              enced  by  prefixing  the  name with a dollr sign and optionally
              include the name in curly braces.  The rules for  a  valid  name
              are  idnetically to those of the standard bourne shell.  This is
              not yet enforced but may be in the future.  When used with curly
              braces no leading or trailing white space is allowed.

              If  a  variable  is not found, it is searched in the environment
              and if found copied to the table of variables.

              Variable functions are available: The name of the function  must
              be followed by at least one space and the at least one argument.
              The following functions are available:


              get    Return a value  described  by  the  argument.   Available
                     arguments are:


                     cwd    The current working directory.

                     homedir
                            The gnupg homedir.

                     sysconfdir
                            GnuPG's system configuration directory.

                     bindir GnuPG's binary directory.

                     libdir GnuPG's library directory.

                     libexecdir
                            GnuPG's library directory for executable files.

                     datadir
                            GnuPG's data directory.

                     serverpid
                            The  PID of the current server. Command /serverpid
                            must have been given to return a useful value.


              unescape args
                     Remove C-style escapes from args.  Note that   and 0 ter-
                     minate  the returned string implicitly.  The string to be
                     converted are  the  entire  arguments  right  behind  the
                     delimiting space of the function name.


              unpercent args

              unpercent+ args
                     Remove  percent  style  ecaping from args.  Note that %00
                     terminates the string implicitly.  The string to be  con-
                     verted are the entire arguments right behind the delimit-
                     ing space of the function name. unpercent+ also maps plus
                     signs to a spaces.


              percent args

              percent+ args
                     Escape the args using percent style ecaping.  Tabs, form-
                     feeds,  linefeeds,  carriage  returns  and   colons   are
                     escaped. percent+ also maps spaces to plus signs.


              errcode arg

              errsource arg

              errstring arg
                     Assume  arg  is  an integer and evaluate it using strtol.
                     Return the gpg-error error code, error source or  a  for-
                     matted string with the error code and error source.



              +

              -

              *

              /

              %      Evaluate  all arguments as long integers using strtol and
                     apply this operator.  A division by zero yields an  empty
                     string.


              !

              |

              &&      Evaluate  all arguments as long integers using strtol and
                     apply the logical oeprators NOT,  OR  or  AND.   The  NOT
                     operator works on the last argument only.





       /definq name var
              Use  content  of the variable var for inquiries with name.  name
              may be an asterisk (*) to match any inquiry.



       /definqfile name file
              Use content of file for inquiries with name.   name  may  be  an
              asterisk (*) to match any inquiry.


       /definqprog name prog
              Run prog for inquiries matching name and pass the entire line to
              it as command line arguments.


       /showdef
              Print all definitions


       /cleardef
              Delete all definitions


       /sendfd file mode
              Open file in mode (which needs to be a valid fopen mode  string)
              and  send  the  file  descriptor to the server.  This is usually
              followed by a command like INPUT FD to set the input source  for
              other commands.


       /recvfd
              Not yet implemented.


       /open var file [mode]
              Open  file and assign the file descriptor to var.  Warning: This
              command is experimental and might change in future versions.


       /close fd
              Close the file descriptor fd.  Warning: This command is  experi-
              mental and might change in future versions.


       /showopen
              Show a listy of open files.


       /serverpid
              Send  the Assuan command GETINFO pid to the server and store the
              returned PID for internal purposes.


       /sleep Sleep for a second.


       /hex

       /nohex Same as the command line option --hex.


       /decode

       /nodecode
              Same as the command line option --decode.


       /subst

       /nosubst
              Enable and disable variable substitution.  It defaults  to  dis-
              abled  unless the command line option --subst has been used.  If
              /subst as been enabled once, leading whitespace is removed  from
              input lines which makes scripts easier to read.


       /while condition

       /end   These  commands  provide  a  way for executing loops.  All lines
              between the while and the corresponding end are executed as long
              as  the  evaluation  of  condition yields a non-zero value.  The
              evaluation is done by passing condition to the strtol  function.
              Example:

           /subst
           /let i 3
           /while $i
             /echo loop couter is $i
             /let i ${- $i 1}
           /end



       /run file
              Run commands from file.


       /bye   Terminate the connection and the program


       /help  Print a list of available control commands.




SEE ALSO
       gpg-agent(1), scdaemon(1)

       The full documentation for this tool is maintained as a Texinfo manual.
       If GnuPG and the info program are properly installed at your site,  the
       command

         info gnupg

       should  give  you access to the complete manual including a menu struc-
       ture and an index.






GnuPG 2.0.9                       2008-10-04              GPG-CONNECT-AGENT(1)