repo: rxvt-unicode-sixel
action: commit
revision: 
path_from: 
revision_from: 73ef5ce6611510f94b5e346ad2819539ce12a3fb:
path_to: 
revision_to: 

commit 73ef5ce6611510f94b5e346ad2819539ce12a3fb
Author: Marc Lehmann 
Date:   Mon Jan 23 12:39:42 2006 +0000

    *** empty log message ***

diff --git a/src/libptytty.h b/src/libptytty.h

--- a/src/libptytty.h
+++ b/src/libptytty.h
@@ -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<<  >>.

-----END OF PAGE-----