miniexpect.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 miniexpect - A very simple expect library for C.
   6
   7 =head1 SYNOPSIS
   8
   9  #include <errno.h>
  10  #include <sys/wait.h>
  11  #include <pcre.h>
  12  #include <miniexpect.h>
  13
  14  mexp_h *h;
  15  h = mexp_spawnl ("ssh", "ssh", "host");
  16  switch (mexp_expect (h, regexps, ovector, ovecsize)) {
  17    ...
  18  }
  19  mexp_close (h);
  20
  21  cc prog.c -o prog -lminiexpect -lpcre
  22
  23 =head1 DESCRIPTION
  24
  25 Miniexpect is a very simple expect-like library for C.  Expect is a
  26 way to control an external program that wants to be run interactively.
  27
  28 Miniexpect has a saner interface than libexpect, and doesn't depend on
  29 Tcl.  It is also thread safe, const-correct and uses modern C
  30 standards.
  31
  32 Miniexpect is a standalone library, except for a single dependency: it
  33 requires the PCRE (Perl Compatible Regular Expressions) library from
  34 L<http://www.pcre.org/>.  The PCRE dependency is fundamental because
  35 we want to offer the most powerful regular expression syntax to match
  36 on, but more importantly because PCRE has a convenient way to detect
  37 partial matches which made this library very simple to implement.
  38
  39 This manual page documents the API.  Examples of how to use the API
  40 can be found in the source directory.
  41
  42 =head1 CONCEPTS
  43
  44 Miniexpect lets you start up an external program, control it (by
  45 sending commands to it), and close it down gracefully.  Two things
  46 make this different from other APIs like L<popen(3)> and L<system(3)>:
  47 Firstly miniexpect creates a pseudoterminal (pty).  Secondly
  48 miniexpect lets you match the output of the program using regular
  49 expressions.  Both of these are handy for controlling interactive
  50 programs that might (for example) ask for passwords, but you can use
  51 miniexpect on just about any external program.
  52
  53 You can control multiple programs at the same time.
  54
  55 =head1 SPAWNING THE SUBPROCESS
  56
  57 There are two calls for creating a subprocess:
  58
  59 B<mexp_h *mexp_spawnl (const char *file, const char *arg, ...);>
  60
  61 This creates a subprocess running the external program C<file> (the
  62 current C<$PATH> is searched unless you give an absolute path).
  63 C<arg, ...> are the arguments to the program.  Usually the first
  64 argument should be the name of the program.
  65
  66 The return value is a handle (see next section).
  67
  68 If there was an error running the subprocess, C<NULL> is returned and
  69 the error is available in C<errno>.
  70
  71 For example, to run an ssh subprocess you could do:
  72
  73  h = mexp_spawnl ("ssh", "ssh", "-l", "root", "host");
  74
  75 or to run a particular ssh binary:
  76
  77  h = mexp_spawnl ("/usr/local/bin/ssh", "ssh", "-l", "root", "host");
  78
  79 An alternative to C<mexp_spawnl> is:
  80
  81 B<mexp_h *mexp_spawnv (const char *file, char **argv);>
  82
  83 This is the same as C<mexp_spawnl> except that you pass the arguments
  84 in a NULL-terminated array.
  85
  86 =head1 HANDLES
  87
  88 After spawning a subprocess, you get back a handle.  There are various
  89 fields in this handle which you can read or write:
  90
  91  struct mexp_h {
  92    int fd;
  93    pid_t pid;
  94
  95 C<fd> is the pty of the subprocess.  You can read and write to this if
  96 you want, although convenience functions are also provided (see
  97 below).  C<pid> is the process ID of the subprocess.  You can send it
  98 signals if you want.
  99
 100    int timeout;
 101
 102 C<timeout> is the timeout in milliseconds (1/1000th of a second) used
 103 by C<mexp_expect> (see below).  You can set this before calling
 104 C<mexp_expect> if you want.  Setting it to -1 means no timeout.  The
 105 default setting is 60000 (60 seconds).
 106
 107    char *buffer;
 108    size_t len;
 109    size_t alloc;
 110
 111 If C<mexp_expect> returns a match then these variables contain the
 112 read buffer.  Note this buffer does not contain the full input from
 113 the process, but it will contain at least the part matched by the
 114 regular expression (and maybe some more).  C<buffer> is the read
 115 buffer and C<len> is the number of bytes of data in the buffer.
 116
 117    size_t read_size;
 118
 119 Callers may set this to the natural size (in bytes) for reads from the
 120 subprocess.  The default is 1024.  Most callers will not need to
 121 change this.
 122
 123    int pcre_error;
 124
 125 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
 126 error code returned by L<pcre_exec(3)> is available here.  For a list
 127 of PCRE error codes, see L<pcreapi(3)>.
 128
 129    void *user1;
 130    void *user2;
 131    void *user3;
 132
 133 Opaque pointers for use by the caller.  The library will not touch
 134 these.
 135
 136  };
 137
 138  typedef struct mexp_h mexp_h;
 139
 140 =head1 CLOSING THE HANDLE
 141
 142 To close the handle and clean up the subprocess, call:
 143
 144 B<int mexp_close (mexp_h *h);>
 145
 146 This returns the status code from the subprocess.  This is in the form
 147 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
 148 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
 149 in C<E<lt>sys/wait.hE<gt>> to parse it.
 150
 151 If there was a system call error, then C<-1> is returned.  The error
 152 will be in C<errno>.
 153
 154 Notes:
 155
 156 =over 4
 157
 158 =item *
 159
 160 Even in error cases, the handle is always closed and its memory is
 161 freed by this call.
 162
 163 =item *
 164
 165 It is normal for the kernel to send SIGHUP to the subprocess.
 166
 167 If the subprocess doesn't catch the SIGHUP, then it will die
 168 with status:
 169
 170  WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
 171
 172 This case should not necessarily be considered an error.
 173
 174 =back
 175
 176 =head1 EXPECT FUNCTION
 177
 178 Miniexpect contains a powerful regular expression matching function
 179 based on L<pcre(3)>:
 180
 181 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
 182 int *ovector, int ovecsize);>
 183
 184 The output of the subprocess is matched against the list of PCRE
 185 regular expressions in C<regexps>.  C<regexps> is a list of regular
 186 expression structures:
 187
 188  struct mexp_regexp {
 189    int r;
 190    const pcre *re;
 191    const pcre_extra *extra;
 192    int options;
 193  };
 194  typedef struct mexp_regexp mexp_regexp;
 195
 196 C<r> is the integer code returned from C<mexp_expect> if this regular
 197 expression matches.  It B<must> be E<gt> 0.  C<r == 0> indicates the
 198 end of the list of regular expressions.  C<re> is the compiled regular
 199 expression.
 200
 201 Possible return values are:
 202
 203 =over 4
 204
 205 =item C<MEXP_TIMEOUT>
 206
 207 No input matched before the timeout (C<h-E<gt>timeout>) was
 208 reached.
 209
 210 =item C<MEXP_EOF>
 211
 212 The subprocess closed the connection.
 213
 214 =item C<MEXP_ERROR>
 215
 216 There was a system call error (eg. from the read call).  The error is
 217 returned in C<errno>.
 218
 219 =item C<MEXP_PCRE_ERROR>
 220
 221 There was a C<pcre_exec> error.  C<h-E<gt>pcre_error> is set to the
 222 error code.  See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
 223 and what they mean.
 224
 225 =item C<r> E<gt> 0
 226
 227 If any regexp matches, the associated integer code (C<regexps[].r>)
 228 is returned.
 229
 230 =back
 231
 232 Notes:
 233
 234 =over 4
 235
 236 =item *
 237
 238 C<regexps> may be NULL or an empty list, which means we don't match
 239 against a regular expression.  This is useful if you just want to wait
 240 for EOF or timeout.
 241
 242 =item *
 243
 244 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
 245 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
 246
 247 =back
 248
 249 =head2 mexp_expect example
 250
 251 It is easier to understand C<mexp_expect> by considering a simple
 252 example.
 253
 254 In this example we are waiting for ssh to either send us a password
 255 prompt, or (if no password was required) a command prompt, and based
 256 on the output we will either send back a password or a command.
 257
 258 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
 259 literal" and is available in C99.  If you need to use an older
 260 compiler, you can just use a local variable instead.
 261
 262  mexp_h *h;
 263  char *errptr;
 264  int offset;
 265  pcre *password_re, *prompt_re;
 266  const int ovecsize = 12;
 267  int ovector[ovecsize];
 268
 269  password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
 270  prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
 271
 272  switch (mexp_expect (h,
 273                       (mexp_regexp[]) {
 274                         { 100, .re = password_re },
 275                         { 101, .re = prompt_re },
 276                         { 0 },
 277                       }, ovector, ovecsize)) {
 278   case 100:
 279     /* here you would send a password */
 280     break;
 281   case 101:
 282     /* here you would send a command */
 283     break;
 284   case MEXP_EOF:
 285     fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
 286     exit (EXIT_FAILURE);
 287   case MEXP_TIMEOUT:
 288     fprintf (stderr, "error: timeout before reaching the prompt\n");
 289     exit (EXIT_FAILURE);
 290   case MEXP_ERROR:
 291     perror ("mexp_expect");
 292     exit (EXIT_FAILURE);
 293   case MEXP_PCRE_ERROR:
 294     fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
 295     exit (EXIT_FAILURE);
 296  }
 297
 298 =head1 SENDING COMMANDS TO THE SUBPROCESS
 299
 300 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
 301 However we also provide a convenience function:
 302
 303 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
 304
 305 This returns the number of bytes, if the whole message was written OK.
 306 If there was an error, -1 is returned and the error is available in
 307 C<errno>.
 308
 309 Notes:
 310
 311 =over 4
 312
 313 =item *
 314
 315 C<mexp_printf> will not do a partial write.  If it cannot write all
 316 the data, then it will return an error.
 317
 318 =item *
 319
 320 This function does not write a newline automatically.  If you want to
 321 send a command followed by a newline you have to do something like:
 322
 323  mexp_printf (h, "exit\n");
 324
 325 =back
 326
 327 =head1 SOURCE
 328
 329 Source is available from:
 330 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
 331
 332 =head1 SEE ALSO
 333
 334 L<pcre(3)>,
 335 L<pcre_exec(3)>,
 336 L<pcreapi(3)>,
 337 L<waitpid(2)>,
 338 L<system(3)>.
 339
 340 =head1 AUTHORS
 341
 342 Richard W.M. Jones (C<rjones at redhat dot com>)
 343
 344 =head1 LICENSE
 345
 346 The library is released under the Library GPL (LGPL) version 2 or at
 347 your option any later version.
 348
 349 =head1 COPYRIGHT
 350
 351 Copyright (C) 2014 Red Hat Inc.