su/pts.h

   1 /*
   2  * Copyright 2013, Tan Chee Eng (@tan-ce)
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17  /*
  18  * pts.h
  19  *
  20  * Manages the pseudo-terminal driver on Linux/Android and provides some
  21  * helper functions to handle raw input mode and terminal window resizing
  22  */
  23
  24 #ifndef _PTS_H_
  25 #define _PTS_H_
  26
  27 /**
  28  * pts_open
  29  *
  30  * Opens a pts device and returns the name of the slave tty device.
  31  *
  32  * Arguments
  33  * slave_name       the name of the slave device
  34  * slave_name_size  the size of the buffer passed via slave_name
  35  *
  36  * Return Values
  37  * on failure either -2 or -1 (errno set) is returned.
  38  * on success, the file descriptor of the master device is returned.
  39  */
  40 int pts_open(char *slave_name, size_t slave_name_size);
  41
  42 /**
  43  * set_stdin_raw
  44  *
  45  * Changes stdin to raw unbuffered mode, disables echo,
  46  * auto carriage return, etc.
  47  *
  48  * Return Value
  49  * on failure -1, and errno is set
  50  * on success 0
  51  */
  52 int set_stdin_raw(void);
  53
  54 /**
  55  * restore_stdin
  56  *
  57  * Restore termios on stdin to the state it was before
  58  * set_stdin_raw() was called. If set_stdin_raw() was
  59  * never called, does nothing and doesn't return an error.
  60  *
  61  * This function is async-safe.
  62  *
  63  * Return Value
  64  * on failure, -1 and errno is set
  65  * on success, 0
  66  */
  67 int restore_stdin(void);
  68
  69 /**
  70  * watch_sigwinch_async
  71  *
  72  * After calling this function, if the application receives
  73  * SIGWINCH, the terminal window size will be read from
  74  * "input" and set on "output".
  75  *
  76  * NOTE: This function blocks SIGWINCH and spawns a thread.
  77  *
  78  * Arguments
  79  * master   A file descriptor of the TTY window size to follow
  80  * slave    A file descriptor of the TTY window size which is
  81  *          to be set on SIGWINCH
  82  *
  83  * Return Value
  84  * on failure, -1 and errno will be set. In this case, no
  85  *      thread has been spawned and SIGWINCH will not be
  86  *      blocked.
  87  * on success, 0
  88  */
  89 int watch_sigwinch_async(int master, int slave);
  90
  91 /**
  92  * watch_sigwinch_cleanup
  93  *
  94  * Cause the SIGWINCH watcher thread to terminate
  95  */
  96 void watch_sigwinch_cleanup(void);
  97
  98 /**
  99  * pump_stdin_async
 100  *
 101  * Forward data from STDIN to the given FD
 102  * in a seperate thread
 103  */
 104 void pump_stdin_async(int outfd);
 105
 106 /**
 107  * pump_stdout_blocking
 108  *
 109  * Forward data from the FD to STDOUT.
 110  * Returns when the remote end of the FD closes.
 111  *
 112  * Before returning, restores stdin settings.
 113  */
 114 void pump_stdout_blocking(int infd);
 115
 116 #endif