--- libptytty/README	2006/01/23 12:27:47	1.3
+++ libptytty/README	2006/01/23 12:37:09	1.4
@@ -3,10 +3,55 @@
     handling
 
 SYNOPSIS
-       -lptytty
+       cc ... -lptytty
+
+       #include <libptytty.h>
+
+       // C++
+       ptytty *pty = ptytty::create ();
+
+       if (!pty->get ())
+         // error allocating pty
+
+       if (we want utmp)
+         pty->login (process_pid, 0, "remote.host");
+       else if (we want utmp AND wtmp/lastlog)
+         pty->login (process_pid, 1, "remote.host");
+
+       // we are done with it
+       delete pty;
+
+       // C
+       PTYTTY pty = ptytty_create ();
+
+       if (!ptytty_get (pty))
+         // error allocating pty
+
+       if (we want utmp)
+         ptytty_login (pty, process_pid, 0, "remote.host");
+       else if (we want utmp AND wtmp/lastlog)
+         ptytty_login (pty, process_pid, 1, "remote.host");
+
+       // we are done with it
+       ptytty_delete (pty);
 
 DESCRIPTION
-    TODO
+    Libptytty is a small library that offers pseudo-tty management in an
+    OS-independent way. It was created out of frustration over the many
+    differences of pty/tty handling in different operating systems for the
+    use inside "rxvt-unicode".
+
+    In addition to offering mere pty/tty management, it also offers session
+    database support (utmp and optional wtmp/lastlog updates for login
+    shells).
+
+    It also supports fork'ing after startup and dropping privileges in the
+    calling process, so in case the calling process gets compromised by the
+    user starting the program there is less to gain, as only the helper
+    process runs with privileges (e.g. setuid/setgid), which reduces the
+    area of attack immensely.
+
+    Libptytty is written in C++, but it also offers a C-only API.
 
 SECURITY CONSIDERATIONS
     *It is of paramount importance that you at least read the following