-=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<It is of paramount importance that you at least read the following
-paragraph!> >>
+ 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<ptytty::init ()> method (C: C<ptytty_init ()
-function) as the very first thing in your program:
+ static void init ();
+ static ptytty *create (); // create a new pty object
- int main (int argc, char *argv[])
- {
- // do nothing here
- ptytty::init ();
- // in C: ptytty_init ();
+ static void drop_privileges ();
+ static void use_helper ();
- // initialise, parse arguments, etc.
- }
+ static bool send_fd (int socket, int fd);
+ static int recv_fd (int socket);
-This checks wether the program runs setuid or setgid. If yes then it will
-fork a helper process and drop privileges.
+protected:
-Some programs need finer control over if and when this helper process
-is started, and if and how to drop privileges. For those programs, the
-methods C<ptytty::use_helper> and C<ptytty::drop_privileges> 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<main> 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<ptytty::init> 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<ptytty::get>.
-
-=item bool success = pty->get ()
-
-Tries to find, allocate and initialise a new pty/tty pair. Returns C<true>
-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<cmd_pid> must be the pid of the process representing the session
-(such as the login shell), C<login_shell> defines wether the session is
-associated with a login, which influences wether wtmp and lastlog entries
-are created, and C<hostname> should identify the "hostname" the user logs
-in from, which often is the value of the C<DISPLAY> 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<ptytty::init ()>.
-
-=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<if (pty) ....>). See
-C<ptytty::create ()>.
-
-=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<delete pty> 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<< <e.giaquinta@glauco.it> >>, Marc Alexander Lehmann
-L<< <rxvt-unicode@schmorp.de> >>.
#ifndef PTYTTY_NO_C_API
+typedef void *PTYTTY;
+
#define DEFINE_METHOD(retval, name, args1, args2) \
extern "C" retval ptytty_ ## name args1 \
{ return ((struct ptytty *)ptytty)->name args2; }
-DEFINE_METHOD(int,pty,(void *ptytty),)
-DEFINE_METHOD(int,tty,(void *ptytty),)
-DEFINE_METHOD(int,get,(void *ptytty),())
-DEFINE_METHOD(void,login,(void *ptytty, int cmd_pid, bool login_shell, const char *hostname),(cmd_pid,login_shell,hostname))
+DEFINE_METHOD(int,pty,(PTYTTY ptytty),)
+DEFINE_METHOD(int,tty,(PTYTTY ptytty),)
+DEFINE_METHOD(int,get,(PTYTTY ptytty),())
+DEFINE_METHOD(void,login,(PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname),(cmd_pid,login_shell,hostname))
-DEFINE_METHOD(void,close_tty,(void *ptytty),())
-DEFINE_METHOD(int,make_controlling_tty,(void *ptytty),())
-DEFINE_METHOD(void,set_utf8_mode,(void *ptytty, int on),(on))
+DEFINE_METHOD(void,close_tty,(PTYTTY ptytty),())
+DEFINE_METHOD(int,make_controlling_tty,(PTYTTY ptytty),())
+DEFINE_METHOD(void,set_utf8_mode,(PTYTTY ptytty, int on),(on))
#define DEFINE_STATIC(retval, name, args) \
extern "C" retval ptytty_ ## name args \
DEFINE_STATIC(void,use_helper,())
DEFINE_STATIC(void,init,())
-DEFINE_STATIC(void *,create,())
+DEFINE_STATIC(PTYTTY ,create,())
-void ptytty_delete (void *ptytty)
+void ptytty_delete (PTYTTY ptytty)
{
delete (struct ptytty *)ptytty;
}
projects / dana / urxvt.git / commitdiff