man pages section 1: User Commands

Exit Print View

Updated: July 2014
 
 

gpg-connect-agent (1)

Name

gpg-connect-agent - Communicate with a running agent

Synopsis

gpg-connect-agent [options][commands]

Description




GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



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

SYNOPSIS
     gpg-connect-agent [options][commands]


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.  Input  is
     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  this
          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  of  the  Registry  entry
          HKCU\Software\GNU\GnuPG:HomeDir.



     --agent-program file
          Specify the agent program to be started if none is run-
          ning.






GnuPG 2.0.22         Last change: 2014-06-17                    1






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



     -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 con-
          nect to any Assuan style socket server.


     -E

     --exec
          Take the rest of the command line as a program and it's
          arguments  and  execute it as an assuan server. Here is
          how you would run gpgsm:
        gpg-connect-agent --exec gpgsm --server
     Note that you may not use options on  the  command  line  in
     this case.


     --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.   Note,  that  commands
          given on the command line are executed after this file.


     -s

     --subst
          Run the command /subst at startup.


     --hex
          Print data lines in a hex format and the  ASCII  repre-
          sentation 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



GnuPG 2.0.22         Last change: 2014-06-17                    2






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



     special commands 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  referenced by prefixing the name with a
          dollar sign and optionally include the  name  in  curly
          braces.   The rules for a valid name are identically 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 envi-
          ronment and if found copied to the table of  variables.

          Variable functions are available: The name of the func-
          tion must be followed by at least one space and the  at
          least one argument.  The following functions are avail-
          able:


          get  Return a value described by the argument.   Avail-
               able 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 2.0.22         Last change: 2014-06-17                    3






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



                    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  \0
               and \x00 terminate the returned string implicitly.
               The string to be converted are  the  entire  argu-
               ments  right  behind  the  delimiting space of the
               function name.


          unpercent args

          unpercent+ args
               Remove percent style  escaping  from  args.   Note
               that  %00  terminates  the string implicitly.  The
               string to be converted are  the  entire  arguments
               right  behind the delimiting space of the function
               name. unpercent+ also maps plus signs to a spaces.


          percent args

          percent+ args
               Escape  the  args  using  percent  style escaping.
               Tabs, formfeeds, 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 formatted string with the  error  code
               and error source.



          +

          -

          *



GnuPG 2.0.22         Last change: 2014-06-17                    4






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



          /

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


          !

          |

          &    Evaluate all arguments as long integers using str-
               tol 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.


     /datafile name
          Write all data lines from the server to the file  name.
          The  file  is opened for writing and created if it does
          not exists.  An existing file is first truncated to  0.
          The  data  written  to the file fully decoded.  Using a
          single dash for name writes to  stdout.   The  file  is
          kept open until a new file is set using this command or
          this command is used without an argument.


     /showdef
          Print all definitions


     /cleardef



GnuPG 2.0.22         Last change: 2014-06-17                    5






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



          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.  Warn-
          ing: This command is experimental and might  change  in
          future versions.


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


     /showopen
          Show a list 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




GnuPG 2.0.22         Last change: 2014-06-17                    6






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



     /nosubst
          Enable  and disable variable substitution.  It defaults
          to disabled 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 or is the string  true  or  yes.   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


     /if condition

     /end These commands provide a way for conditional execution.
          All  lines between the if and the corresponding end are
          executed only if the evaluation of condition  yields  a
          non-zero value or is the string true or yes.  The eval-
          uation is done by passing condition to the strtol func-
          tion.


     /run file
          Run commands from file.


     /bye Terminate the connection and the program


     /help
          Print a list of available control commands.





ATTRIBUTES
     See   attributes(5)   for   descriptions  of  the  following
     attributes:



GnuPG 2.0.22         Last change: 2014-06-17                    7






GNU Privacy Guard                            GPG-CONNECT-AGENT(1)



     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | crypto/gnupg     |
     +---------------+------------------+
     |Stability      | Uncommitted      |
     +---------------+------------------+
SEE ALSO
     gpg-agent(1), scdaemon(1)

     The full documentation for this tool is maintained as a Tex-
     info  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 structure and an index.





NOTES
     This   software   was   built   from   source  available  at
     https://java.net/projects/solaris-userland.   The   original
     community       source       was       downloaded       from
     ftp://ftp.gnupg.org/gcrypt/gnupg/gnupg-2.0.22.tar.bz2

     Further information about this software can be found on  the
     open source community website at http://www.gnupg.org/.
























GnuPG 2.0.22         Last change: 2014-06-17                    8