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    ssize_t next_match;
 118
 119 If C<mexp_expect> returns a match, then C<next_match> points to the
 120 first byte in the buffer I<after> the fully matched expression.  (It
 121 may be C<-1> which means it is invalid).  The next time that
 122 C<mexp_expect> is called, it will start by consuming the data
 123 C<buffer[next_match...len-1]>.  Callers may also need to read from
 124 that point in the buffer before calling L<read(2)> on the file
 125 descriptor.  Callers may also set this, for example setting it to
 126 C<-1> in order to ignore the remainder of the buffer.  In most cases
 127 callers can ignore this field, and C<mexp_expect> will just do the
 128 right thing when called repeatedly.
 129
 130    size_t read_size;
 131
 132 Callers may set this to the natural size (in bytes) for reads from the
 133 subprocess.  The default is 1024.  Most callers will not need to
 134 change this.
 135
 136    int pcre_error;
 137
 138 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
 139 error code returned by L<pcre_exec(3)> is available here.  For a list
 140 of PCRE error codes, see L<pcreapi(3)>.
 141
 142    void *user1;
 143    void *user2;
 144    void *user3;
 145
 146 Opaque pointers for use by the caller.  The library will not touch
 147 these.
 148
 149  };
 150
 151  typedef struct mexp_h mexp_h;
 152
 153 =head1 CLOSING THE HANDLE
 154
 155 To close the handle and clean up the subprocess, call:
 156
 157 B<int mexp_close (mexp_h *h);>
 158
 159 This returns the status code from the subprocess.  This is in the form
 160 of a L<waitpid(2)>/L<system(3)> status so you have to use the macros
 161 C<WIFEXITED>, C<WEXITSTATUS>, C<WIFSIGNALED>, C<WTERMSIG> etc defined
 162 in C<E<lt>sys/wait.hE<gt>> to parse it.
 163
 164 If there was a system call error, then C<-1> is returned.  The error
 165 will be in C<errno>.
 166
 167 Notes:
 168
 169 =over 4
 170
 171 =item *
 172
 173 Even in error cases, the handle is always closed and its memory is
 174 freed by this call.
 175
 176 =item *
 177
 178 It is normal for the kernel to send SIGHUP to the subprocess.
 179
 180 If the subprocess doesn't catch the SIGHUP, then it will die
 181 with status:
 182
 183  WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP
 184
 185 This case should not necessarily be considered an error.
 186
 187 =back
 188
 189 =head1 EXPECT FUNCTION
 190
 191 Miniexpect contains a powerful regular expression matching function
 192 based on L<pcre(3)>:
 193
 194 B<int mexp_expect (mexp_h *h, const mexp_regexp *regexps,
 195 int *ovector, int ovecsize);>
 196
 197 The output of the subprocess is matched against the list of PCRE
 198 regular expressions in C<regexps>.  C<regexps> is a list of regular
 199 expression structures:
 200
 201  struct mexp_regexp {
 202    int r;
 203    const pcre *re;
 204    const pcre_extra *extra;
 205    int options;
 206  };
 207  typedef struct mexp_regexp mexp_regexp;
 208
 209 C<r> is the integer code returned from C<mexp_expect> if this regular
 210 expression matches.  It B<must> be E<gt> 0.  C<r == 0> indicates the
 211 end of the list of regular expressions.  C<re> is the compiled regular
 212 expression.
 213
 214 Possible return values are:
 215
 216 =over 4
 217
 218 =item C<MEXP_TIMEOUT>
 219
 220 No input matched before the timeout (C<h-E<gt>timeout>) was
 221 reached.
 222
 223 =item C<MEXP_EOF>
 224
 225 The subprocess closed the connection.
 226
 227 =item C<MEXP_ERROR>
 228
 229 There was a system call error (eg. from the read call).  The error is
 230 returned in C<errno>.
 231
 232 =item C<MEXP_PCRE_ERROR>
 233
 234 There was a C<pcre_exec> error.  C<h-E<gt>pcre_error> is set to the
 235 error code.  See L<pcreapi(3)> for a list of the C<PCRE_*> error codes
 236 and what they mean.
 237
 238 =item C<r> E<gt> 0
 239
 240 If any regexp matches, the associated integer code (C<regexps[].r>)
 241 is returned.
 242
 243 =back
 244
 245 Notes:
 246
 247 =over 4
 248
 249 =item *
 250
 251 C<regexps> may be NULL or an empty list, which means we don't match
 252 against a regular expression.  This is useful if you just want to wait
 253 for EOF or timeout.
 254
 255 =item *
 256
 257 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
 258 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
 259
 260 =item *
 261
 262 If multiple regular expressions are passed, then they are checked in
 263 turn and the I<first> regular expression that matches is returned
 264 I<even if the match happens later in the input than another regular
 265 expression>.
 266
 267 For example if the input is C<"hello world"> and you pass the two
 268 regular expressions:
 269
 270  regexps[0].re = world
 271  regexps[1].re = hello
 272
 273 then the first regular expression (C<"world">) may match and the
 274 C<"hello"> part of the input may be ignored.
 275
 276 In some cases this can even lead to unpredictable matching.  In the
 277 case above, if we only happened to read C<"hello wor">, then the
 278 second regular expression (C<"hello">) I<would> match.
 279
 280 If this is a concern, combine your regular expressions into a single
 281 one, eg. C<(hello)|(world)>.
 282
 283 =back
 284
 285 =head2 mexp_expect example
 286
 287 It is easier to understand C<mexp_expect> by considering a simple
 288 example.
 289
 290 In this example we are waiting for ssh to either send us a password
 291 prompt, or (if no password was required) a command prompt, and based
 292 on the output we will either send back a password or a command.
 293
 294 The unusual C<(mexp_regexp[]){...}> syntax is called a "compound
 295 literal" and is available in C99.  If you need to use an older
 296 compiler, you can just use a local variable instead.
 297
 298  mexp_h *h;
 299  char *errptr;
 300  int offset;
 301  pcre *password_re, *prompt_re;
 302  const int ovecsize = 12;
 303  int ovector[ovecsize];
 304
 305  password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
 306  prompt_re = pcre_compile ("[$#] ", 0, &errptr, &offset, NULL);
 307
 308  switch (mexp_expect (h,
 309                       (mexp_regexp[]) {
 310                         { 100, .re = password_re },
 311                         { 101, .re = prompt_re },
 312                         { 0 },
 313                       }, ovector, ovecsize)) {
 314   case 100:
 315     /* here you would send a password */
 316     break;
 317   case 101:
 318     /* here you would send a command */
 319     break;
 320   case MEXP_EOF:
 321     fprintf (stderr, "error: ssh closed the connection unexpectedly\n");
 322     exit (EXIT_FAILURE);
 323   case MEXP_TIMEOUT:
 324     fprintf (stderr, "error: timeout before reaching the prompt\n");
 325     exit (EXIT_FAILURE);
 326   case MEXP_ERROR:
 327     perror ("mexp_expect");
 328     exit (EXIT_FAILURE);
 329   case MEXP_PCRE_ERROR:
 330     fprintf (stderr, "error: PCRE error: %d\n", h->pcre_error);
 331     exit (EXIT_FAILURE);
 332  }
 333
 334 =head1 SENDING COMMANDS TO THE SUBPROCESS
 335
 336 You can write to the subprocess simply by writing to C<h-E<gt>fd>.
 337 However we also provide a convenience function:
 338
 339 B<int mexp_printf (mexp_h *h, const char *fs, ...);>
 340
 341 This returns the number of bytes, if the whole message was written OK.
 342 If there was an error, -1 is returned and the error is available in
 343 C<errno>.
 344
 345 Notes:
 346
 347 =over 4
 348
 349 =item *
 350
 351 C<mexp_printf> will not do a partial write.  If it cannot write all
 352 the data, then it will return an error.
 353
 354 =item *
 355
 356 This function does not write a newline automatically.  If you want to
 357 send a command followed by a newline you have to do something like:
 358
 359  mexp_printf (h, "exit\n");
 360
 361 =back
 362
 363 =head1 SOURCE
 364
 365 Source is available from:
 366 L<http://git.annexia.org/?p=miniexpect.git;a=summary>
 367
 368 =head1 SEE ALSO
 369
 370 L<pcre(3)>,
 371 L<pcre_exec(3)>,
 372 L<pcreapi(3)>,
 373 L<waitpid(2)>,
 374 L<system(3)>.
 375
 376 =head1 AUTHORS
 377
 378 Richard W.M. Jones (C<rjones at redhat dot com>)
 379
 380 =head1 LICENSE
 381
 382 The library is released under the Library GPL (LGPL) version 2 or at
 383 your option any later version.
 384
 385 =head1 COPYRIGHT
 386
 387 Copyright (C) 2014 Red Hat Inc.