ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libptytty/README
(Generate patch)

Comparing libptytty/README (file contents):
Revision 1.4 by root, Mon Jan 23 12:37:09 2006 UTC vs.
Revision 1.6 by ayin, Mon Sep 11 14:11:26 2006 UTC

… …
32 else if (we want utmp AND wtmp/lastlog) 32 else if (we want utmp AND wtmp/lastlog)
33 ptytty_login (pty, process_pid, 1, "remote.host"); 33 ptytty_login (pty, process_pid, 1, "remote.host");
34 34
35 // we are done with it 35 // we are done with it
36 ptytty_delete (pty); 36 ptytty_delete (pty);
37
38 See also the eg/ directory, which currently contains the c-sample.c file
39 that spawns a loginshell from C using libptytty.
37 40
38DESCRIPTION 41DESCRIPTION
39 Libptytty is a small library that offers pseudo-tty management in an 42 Libptytty is a small library that offers pseudo-tty management in an
40 OS-independent way. It was created out of frustration over the many 43 OS-independent way. It was created out of frustration over the many
41 differences of pty/tty handling in different operating systems for the 44 differences of pty/tty handling in different operating systems for the
… …
68 // in C: ptytty_init (); 71 // in C: ptytty_init ();
69 72
70 // initialise, parse arguments, etc. 73 // initialise, parse arguments, etc.
71 } 74 }
72 75
73 This checks wether the program runs setuid or setgid. If yes then it 76 This checks whether the program runs setuid or setgid. If yes then it
74 will fork a helper process and drop privileges. 77 will fork a helper process and drop privileges.
75 78
76 Some programs need finer control over if and when this helper process is 79 Some programs need finer control over if and when this helper process is
77 started, and if and how to drop privileges. For those programs, the 80 started, and if and how to drop privileges. For those programs, the
78 methods "ptytty::use_helper" and "ptytty::drop_privileges" are more 81 methods "ptytty::use_helper" and "ptytty::drop_privileges" are more
… …
83 ptytty::init () 86 ptytty::init ()
84 The default way to initialise libptytty. Must be called imemdiately 87 The default way to initialise libptytty. Must be called imemdiately
85 as the first thing in the "main" function, or earlier e.g. during 88 as the first thing in the "main" function, or earlier e.g. during
86 static construction time. The earlier, the better. 89 static construction time. The earlier, the better.
87 90
88 This method checks wether the program runs with setuid/setgid 91 This method checks whether the program runs with setuid/setgid
89 permissions and, if yes, spawns a helper process for pty/tty 92 permissions and, if yes, spawns a helper process for pty/tty
90 management. IT then drops the privileges completely, so the actual 93 management. It then drops the privileges completely, so the actual
91 program runs without setuid/setgid privileges. 94 program runs without setuid/setgid privileges.
92 95
93 ptytty::use_helper () 96 ptytty::use_helper ()
94 Tries to start a helper process that retains privileges even when 97 Tries to start a helper process that retains privileges even when
95 the calling process does not. This is usually called from 98 the calling process does not. This is usually called from
… …
98 privileges at startup, or when you are not running setuid/setgid but 101 privileges at startup, or when you are not running setuid/setgid but
99 want to drop privileges (e.g. when running as a root-started 102 want to drop privileges (e.g. when running as a root-started
100 daemon). 103 daemon).
101 104
102 This method will try not to start more than one helper process. The 105 This method will try not to start more than one helper process. The
103 same helper process cna usually be used form the process starting it 106 same helper process can usually be used both from the process
104 an all its fork'ed (not exec'ed) children 107 starting it and all its fork'ed (not exec'ed) children.
105 108
106 ptytty::drop_privileges () 109 ptytty::drop_privileges ()
107 Drops privileges completely, i.e. sets real, effective and saved 110 Drops privileges completely, i.e. sets real, effective and saved
108 user id to the real user id. Also aborts if this cnanot be achieved. 111 user id to the real user id. Also aborts if this cannot be achieved.
109 Useful to make sure that the process doesn't run with special 112 Useful to make sure that the process doesn't run with special
110 privileges. 113 privileges.
111 114
112 bool success = ptytty::send_fd (int socket, int fd) 115 bool success = ptytty::send_fd (int socket, int fd)
113 Utility method to send a file descriptor over a unix domain socket. 116 Utility method to send a file descriptor over a unix domain socket.
… …
140 "true" when successful. 143 "true" when successful.
141 144
142 pty->login (int cmd_pid, bool login_shell, const char *hostname) 145 pty->login (int cmd_pid, bool login_shell, const char *hostname)
143 Creates an entry in the systems session database(s) (utmp, wtmp, 146 Creates an entry in the systems session database(s) (utmp, wtmp,
144 lastlog). "cmd_pid" must be the pid of the process representing the 147 lastlog). "cmd_pid" must be the pid of the process representing the
145 session (such as the login shell), "login_shell" defines wether the 148 session (such as the login shell), "login_shell" defines whether the
146 session is associated with a login, which influences wether wtmp and 149 session is associated with a login, which influences whether wtmp and
147 lastlog entries are created, and "hostname" should identify the 150 lastlog entries are created, and "hostname" should identify the
148 "hostname" the user logs in from, which often is the value of the 151 "hostname" the user logs in from, which often is the value of the
149 "DISPLAY" variable or tty line in case of local logins. 152 "DISPLAY" variable or tty line in case of local logins.
150 153
151 Calling this method is optional. A session starts at the time of the 154 Calling this method is optional. A session starts at the time of the
… …
158 Tries to make the pty/tty pair the controlling terminal of the 161 Tries to make the pty/tty pair the controlling terminal of the
159 current process. Useful after forking in the child/tty process. 162 current process. Useful after forking in the child/tty process.
160 163
161 pty->set_utf8_mode (bool on) 164 pty->set_utf8_mode (bool on)
162 On systems supporting special UTF-8 line disciplines (e.g. Linux), 165 On systems supporting special UTF-8 line disciplines (e.g. Linux),
163 tries to enable it for the given pty. Can be called at any time to 166 this tries to enable this discipline for the given pty. Can be
164 change the mode. 167 called at any time to change the mode.
165 168
166C INTERFACE: THE ptytty FAMILY OF FUNCTIONS 169C INTERFACE: THE ptytty FAMILY OF FUNCTIONS
167 ptytty_init () 170 ptytty_init ()
168 See "ptytty::init ()". 171 See "ptytty::init ()".
169 172
170 PTYTTY ptytty_create () 173 PTYTTY ptytty_create ()
171 Creates a new opaque PTYTTY object and returns it. Do not try to 174 Creates a new opaque PTYTTY object and returns it. Do not try to
172 access it in any way excecp by testing it for truthness (e.g. "if 175 access it in any way except by testing it for truthness (e.g. "if
173 (pty) ...."). See "ptytty::create ()". 176 (pty) ...."). See "ptytty::create ()".
174 177
175 int ptytty_pty (PTYTTY ptytty) 178 int ptytty_pty (PTYTTY ptytty)
176 Return the pty file descriptor. See "pty->pty". 179 Return the pty file descriptor. See "pty->pty".
177 180

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines