miniexpect.h

   1 /* miniexpect
   2  * Copyright (C) 2014 Red Hat Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  */
  18
  19 #ifndef MINIEXPECT_H_
  20 #define MINIEXPECT_H_
  21
  22 #include <unistd.h>
  23
  24 #include <pcre.h>
  25
  26 /* This handle is created per subprocess that is spawned. */
  27 struct mexp_h {
  28   int fd;                       /* File descriptor pointing to pty. */
  29   pid_t pid;                    /* Subprocess PID. */
  30
  31   /* Timeout (milliseconds, 1/1000th seconds).  The caller may set
  32    * this before calling mexp_expect.  Set it to -1 to mean no
  33    * timeout.  The default is 60000 (= 60 seconds).
  34    */
  35   int timeout;
  36
  37   /* The read buffer is allocated by the library when mexp_expect is
  38    * called.  It is available so you can examine the buffer to see
  39    * what part of the regexp matched.  Note this buffer does not
  40    * contain the full input from the process, but it will contain at
  41    * least the part matched by the regular expression (and maybe some
  42    * more).
  43    */
  44   char *buffer;                 /* Read buffer. */
  45   size_t len;                   /* Length of data in the buffer. */
  46   size_t alloc;                 /* Allocated size of the buffer. */
  47
  48   /* The caller may set this to set the size (in bytes) for reads from
  49    * the subprocess.  The default is 1024.
  50    */
  51   size_t read_size;
  52
  53   /* Opaque pointers for use of the caller.  The library will not
  54    * touch these.
  55    */
  56   void *user1;
  57   void *user2;
  58   void *user3;
  59 };
  60 typedef struct mexp_h mexp_h;
  61
  62 /* Spawn a subprocess.
  63  *
  64  * If successful it returns a handle.  If it fails, it returns NULL
  65  * and sets errno.
  66  */
  67 extern mexp_h *mexp_spawnv (const char *file, char **argv);
  68
  69 /* Same as mexp_spawnv, but it uses a NULL-terminated variable length
  70  * list of arguments.
  71  */
  72 extern mexp_h *mexp_spawnl (const char *file, const char *arg, ...);
  73
  74 /* Close the handle and clean up the subprocess.
  75  *
  76  * This returns:
  77  *   0:   successful close, subprocess exited cleanly.
  78  *   -1:  error in system call, see errno.
  79  *   > 0: exit status of subprocess if it didn't exit cleanly.  Use
  80  *        WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG etc macros to
  81  *        examine this.
  82  *
  83  * Notes:
  84  *
  85  * - Even in the error cases, the handle is always closed and
  86  *   freed by this call.
  87  *
  88  * - It is normal for the kernel to send SIGHUP to the subprocess.
  89  *   If the subprocess doesn't catch the SIGHUP, then it will die
  90  *   (WIFSIGNALED (status) && WTERMSIG (status) == SIGHUP).  This
  91  *   case should not necessarily be considered an error.
  92  */
  93 extern int mexp_close (mexp_h *h);
  94
  95 enum mexp_status {
  96   MEXP_EOF = 0,
  97   MEXP_ERROR = 1,
  98   MEXP_TIMEOUT = 2,
  99   MEXP_MATCHED = 3,
 100   MEXP_PCRE_ERROR = 4,
 101 };
 102
 103 /* Expect some output from the subprocess.  Match the output against
 104  * the PCRE regular expression.
 105  *
 106  * 'code', 'extra', 'options', 'ovector' and 'ovecsize' are passed
 107  * through to the pcre_exec function.  See pcreapi(3).
 108  *
 109  * If you want to match multiple strings, you have to combine them
 110  * into a single regexp, eg. "([Pp]assword)|([Ll]ogin)|([Ff]ailed)".
 111  * Then examine ovector[2], ovector[4], ovector[6] to see if they
 112  * contain '>= 0' or '-1'.  See the pcreapi(3) man page for further
 113  * information.
 114  *
 115  * 'code' may be NULL, which means we don't match against a regular
 116  * expression.  This is useful if you just want to wait for EOF or
 117  * timeout.
 118  *
 119  * This can return:
 120  *
 121  *   MEXP_MATCHED:
 122  *     The input matched the regular expression.  Use ovector
 123  *     to find out what matched in the buffer (mexp_h->buffer).
 124  *   MEXP_TIMEOUT:
 125  *     No input matched before the timeout (mexp_h->timeout) was reached.
 126  *   MEXP_EOF:
 127  *     The subprocess closed the connection.
 128  *   MEXP_ERROR:
 129  *     There was a system call error (eg. from the read call).  See errno.
 130  *   MEXP_PCRE_ERROR
 131  *     There was a pcre_exec error.  *pcre_ret is set to the error code
 132  *     (see pcreapi(3) for a list of PCRE_* error codes and what they mean).
 133  */
 134 extern enum mexp_status mexp_expect (mexp_h *h, const pcre *code,
 135                                      const pcre_extra *extra,
 136                                      int options, int *ovector, int ovecsize,
 137                                      int *pcre_ret);
 138
 139 /* This is a convenience function for writing something (eg. a
 140  * password or command) to the subprocess.  You could do this by
 141  * writing directly to 'h->fd', but this function does all the error
 142  * checking for you.
 143  *
 144  * Returns the number of bytes if the whole message was written OK
 145  * (partial writes are not possible with this function), or -1 if
 146  * there was an error (check errno).
 147  */
 148 extern int mexp_printf (mexp_h *h, const char *fs, ...)
 149   __attribute__((format(printf,2,3)));
 150
 151 #endif /* MINIEXPECT_H_ */