--- rxvt-unicode/src/libptytty.h 2006/01/23 12:37:59 1.4 +++ rxvt-unicode/src/libptytty.h 2006/01/23 12:39:42 1.5 @@ -1,215 +1,68 @@ -=head1 NAME +// This file is part of libptytty. Do not make local modifications. +// http://software.schmorp.de/pkg/libptytty -libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog handling +#ifndef LIBPTYTTY_H_ /* public libptytty header file */ +#define LIBPTYTTY_H_ -=head1 SYNOPSIS +#ifdef __cplusplus - -lptytty +// c++ api -=head1 DESCRIPTION +struct ptytty { + int pty; // pty file descriptor; connected to rxvt + int tty; // tty file descriptor; connected to child -TODO + virtual ~ptytty () + { + } -=head1 SECURITY CONSIDERATIONS + virtual bool get () = 0; + virtual void login (int cmd_pid, bool login_shell, const char *hostname) = 0; -I<< B >> + void close_tty (); + bool make_controlling_tty (); + void set_utf8_mode (bool on); -If you are a typical terminal-like program that just wants one or more -ptys, you should call the C method (C: C and C are more -useful. + ptytty () + : pty(-1), tty(-1) + { + } +}; -=head1 C++ INTERFACE: THE ptytty CLASS +#else -=head2 STATIC METHODS +// c api -=over 4 +typedef void *PTYTTY; -=item ptytty::init () +int ptytty_pty (PTYTTY ptytty); +int ptytty_tty (PTYTTY ptytty); +void ptytty_delete (PTYTTY ptytty); +int ptytty_get (PTYTTY ptytty); +void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname); -The default way to initialise libptytty. Must be called imemdiately as -the first thing in the C
function, or earlier e.g. during static -construction time. The earlier, the better. +void ptytty_close_tty (PTYTTY ptytty); +int ptytty_make_controlling_tty (PTYTTY ptytty); +void ptytty_set_utf8_mode (PTYTTY ptytty, int on); -This method checks wether the program runs with setuid/setgid permissions -and, if yes, spawns a helper process for pty/tty management. IT then -drops the privileges completely, so the actual program runs without -setuid/setgid privileges. +void ptytty_init (); +PTYTTY ptytty_create (); -=item ptytty::use_helper () +void ptytty_drop_privileges (); +void ptytty_use_helper (); -Tries to start a helper process that retains privileges even when the -calling process does not. This is usually called from C when -it detects that the program is running setuid or setgid, but can be called -manually if it is inconvinient to drop privileges at startup, or when -you are not running setuid/setgid but want to drop privileges (e.g. when -running as a root-started daemon). +#endif -This method will try not to start more than one helper process. The same -helper process can usually be used from the process starting it an all its -fork'ed (not exec'ed) children. +#endif -Please note that starting a helper process after dropping privileges makes -no sense. - -=item ptytty::drop_privileges () - -Drops privileges completely, i.e. sets real, effective and saved user id -to the real user id. Also aborts if this cnanot be achieved. Useful to -make sure that the process doesn't run with special privileges. - -=item bool success = ptytty::send_fd (int socket, int fd) - -Utility method to send a file descriptor over a unix domain -socket. Returns true if successful, false otherwise. This method is only -exposed for your convinience and is not required for normal operation. - -=item int fd = ptytty::recv_fd (int socket) - -Utility method to receive a file descriptor over a unix domain -socket. Returns the fd if sucecssful and C<-1> otherwise. This method -is only exposed for your convinience and is not required for normal -operation. - -=item ptytty *pty = ptytty::create () - -Creates new ptytty object. Creation does not yet do anything besides -allocating the structure. - -A static method is used because the actual ptytty implementation can -differ at runtime, so you need a dynamic object creation facility. - -=back - - -=head2 DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS - -=over 4 - -=item int pty_fd = pty->pty - -=item int tty_fd = pty->tty - -These members contain the pty and tty file descriptors, respectively. They -initially contain C<-1> until a successful to C. - -=item bool success = pty->get () - -Tries to find, allocate and initialise a new pty/tty pair. Returns C -when successful. - -=item pty->login (int cmd_pid, bool login_shell, const char *hostname) - -Creates an entry in the systems session database(s) (utmp, wtmp, lastlog). -C must be the pid of the process representing the session -(such as the login shell), C defines wether the session is -associated with a login, which influences wether wtmp and lastlog entries -are created, and C should identify the "hostname" the user logs -in from, which often is the value of the C variable or tty line -in case of local logins. - -Calling this method is optional. A session starts at the time of the login -call and extends until the ptytty object is destroyed. - -=item pty->close_tty () - -Closes the tty. Useful after forking in the parent/pty process. - -=item bool success = pty->make_controlling_tty () - -Tries to make the pty/tty pair the controlling terminal of the current -process. Useful after forking in the child/tty process. - -=item pty->set_utf8_mode (bool on) - -On systems supporting special UTF-8 line disciplines (e.g. Linux), tries -to enable it for the given pty. Can be called at any time to change the -mode. - -=back - - -=head1 C INTERFACE: THE ptytty FAMILY OF FUNCTIONS - -=over 4 - -=item ptytty_init () - -See C. - -=item PTYTTY ptytty_create () - -Creates a new opaque PTYTTY object and returns it. Do not try to access it -in any way excecp by testing it for truthness (e.g. C). See -C. - -=item int ptytty_pty (PTYTTY ptytty) - -Return the pty file descriptor. See C<< pty->pty >>. - -=item int ptytty_tty (PTYTTY ptytty) - -Return the tty file descriptor. See C<< pty->tty >>. - -=item void ptytty_delete (PTYTTY ptytty) - -Destroys the PTYTTY object, freeing the pty/tty pair and cleaning up the -utmp/wtmp/lastlog databases, if initialised/used. Same as C in -C++. - -=item int ptytty_get (PTYTTY ptytty) - -See C<< pty->get >>, returns 0 in case of an error, non-zero otherwise. - -=item void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname) - -See C<< pty->login >>. - -=item void ptytty_close_tty (PTYTTY ptytty) - -See C<< pty->close_tty >>. - -=item int ptytty_make_controlling_tty (PTYTTY ptytty) - -See C<< pty->make_controlling_tty >>. - -=item void ptytty_set_utf8_mode (PTYTTY ptytty, int on) - -See C<< pty->set_utf8_mode >>. - -=item void ptytty_drop_privileges () - -See C<< ptytty::drop_privileges >>. - -=item void ptytty_use_helper () - -See C<< ptytty::use_helper >>. - -=back - - -=head1 BUGS - -You kiddin'? - -=head1 AUTHORS - -Emanuele Giaquinta L<< >>, Marc Alexander Lehmann -L<< >>.