[ViewVC] Diff of: cvs/rxvt-unicode/src/libptytty.h

Comparing rxvt-unicode/src/libptytty.h (file contents):
Revision 1.3 by root, Mon Jan 23 12:05:12 2006 UTC vs.
Revision 1.4 by root, Mon Jan 23 12:37:59 2006 UTC

1	// This file is part of libptytty. Do not make local modifications.	1	=head1 NAME
2	// http://software.schmorp.de/pkg/libptytty
3		2
4	#ifndef LIBPTYTTY_H_ /* public libptytty header file */	3	libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog handling
5	#define LIBPTYTTY_H_
6		4
7	#ifdef __cplusplus	5	=head1 SYNOPSIS
8		6
9	// c++ api	7	-lptytty
10		8
11	struct ptytty {	9	=head1 DESCRIPTION
12	int pty; // pty file descriptor; connected to rxvt
13	int tty; // tty file descriptor; connected to child
14		10
15	virtual ~ptytty ()	11	TODO
		12
		13	=head1 SECURITY CONSIDERATIONS
		14
		15	I<< B<It is of paramount importance that you at least read the following
		16	paragraph!> >>
		17
		18	If you are a typical terminal-like program that just wants one or more
		19	ptys, you should call the C<ptytty::init ()> method (C: C<ptytty_init ()
		20	function) as the very first thing in your program:
		21
		22	int main (int argc, char *argv[])
16	{	23	{
		24	// do nothing here
		25	ptytty::init ();
		26	// in C: ptytty_init ();
		27
		28	// initialise, parse arguments, etc.
17	}	29	}
18		30
19	virtual bool get () = 0;	31	This checks wether the program runs setuid or setgid. If yes then it will
		32	fork a helper process and drop privileges.
		33
		34	Some programs need finer control over if and when this helper process
		35	is started, and if and how to drop privileges. For those programs, the
		36	methods C<ptytty::use_helper> and C<ptytty::drop_privileges> are more
		37	useful.
		38
		39	=head1 C++ INTERFACE: THE ptytty CLASS
		40
		41	=head2 STATIC METHODS
		42
		43	=over 4
		44
		45	=item ptytty::init ()
		46
		47	The default way to initialise libptytty. Must be called imemdiately as
		48	the first thing in the C<main> function, or earlier e.g. during static
		49	construction time. The earlier, the better.
		50
		51	This method checks wether the program runs with setuid/setgid permissions
		52	and, if yes, spawns a helper process for pty/tty management. IT then
		53	drops the privileges completely, so the actual program runs without
		54	setuid/setgid privileges.
		55
		56	=item ptytty::use_helper ()
		57
		58	Tries to start a helper process that retains privileges even when the
		59	calling process does not. This is usually called from C<ptytty::init> when
		60	it detects that the program is running setuid or setgid, but can be called
		61	manually if it is inconvinient to drop privileges at startup, or when
		62	you are not running setuid/setgid but want to drop privileges (e.g. when
		63	running as a root-started daemon).
		64
		65	This method will try not to start more than one helper process. The same
		66	helper process can usually be used from the process starting it an all its
		67	fork'ed (not exec'ed) children.
		68
		69	Please note that starting a helper process after dropping privileges makes
		70	no sense.
		71
		72	=item ptytty::drop_privileges ()
		73
		74	Drops privileges completely, i.e. sets real, effective and saved user id
		75	to the real user id. Also aborts if this cnanot be achieved. Useful to
		76	make sure that the process doesn't run with special privileges.
		77
		78	=item bool success = ptytty::send_fd (int socket, int fd)
		79
		80	Utility method to send a file descriptor over a unix domain
		81	socket. Returns true if successful, false otherwise. This method is only
		82	exposed for your convinience and is not required for normal operation.
		83
		84	=item int fd = ptytty::recv_fd (int socket)
		85
		86	Utility method to receive a file descriptor over a unix domain
		87	socket. Returns the fd if sucecssful and C<-1> otherwise. This method
		88	is only exposed for your convinience and is not required for normal
		89	operation.
		90
		91	=item ptytty *pty = ptytty::create ()
		92
		93	Creates new ptytty object. Creation does not yet do anything besides
		94	allocating the structure.
		95
		96	A static method is used because the actual ptytty implementation can
		97	differ at runtime, so you need a dynamic object creation facility.
		98
		99	=back
		100
		101
		102	=head2 DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS
		103
		104	=over 4
		105
		106	=item int pty_fd = pty->pty
		107
		108	=item int tty_fd = pty->tty
		109
		110	These members contain the pty and tty file descriptors, respectively. They
		111	initially contain C<-1> until a successful to C<ptytty::get>.
		112
		113	=item bool success = pty->get ()
		114
		115	Tries to find, allocate and initialise a new pty/tty pair. Returns C<true>
		116	when successful.
		117
20	virtual void login (int cmd_pid, bool login_shell, const char *hostname) = 0;	118	=item pty->login (int cmd_pid, bool login_shell, const char *hostname)
21		119
22	void close_tty ();	120	Creates an entry in the systems session database(s) (utmp, wtmp, lastlog).
23	bool make_controlling_tty ();	121	C<cmd_pid> must be the pid of the process representing the session
24	void set_utf8_mode (bool on);	122	(such as the login shell), C<login_shell> defines wether the session is
		123	associated with a login, which influences wether wtmp and lastlog entries
		124	are created, and C<hostname> should identify the "hostname" the user logs
		125	in from, which often is the value of the C<DISPLAY> variable or tty line
		126	in case of local logins.
25		127
26	static void init ();	128	Calling this method is optional. A session starts at the time of the login
27	static ptytty *create (); // create a new pty object	129	call and extends until the ptytty object is destroyed.
28		130
29	static void drop_privileges ();	131	=item pty->close_tty ()
30	static void use_helper ();
31		132
32	static bool send_fd (int socket, int fd);	133	Closes the tty. Useful after forking in the parent/pty process.
33	static int recv_fd (int socket);
34		134
35	protected:	135	=item bool success = pty->make_controlling_tty ()
36		136
37	ptytty ()	137	Tries to make the pty/tty pair the controlling terminal of the current
38	: pty(-1), tty(-1)	138	process. Useful after forking in the child/tty process.
39	{
40	}
41	};
42		139
43	#else	140	=item pty->set_utf8_mode (bool on)
44		141
45	// c api	142	On systems supporting special UTF-8 line disciplines (e.g. Linux), tries
46	int ptytty_pty (void *ptytty);	143	to enable it for the given pty. Can be called at any time to change the
47	int ptytty_tty (void *ptytty);	144	mode.
48	void ptytty_delete (void *ptytty);	145
49	int ptytty_get (void *ptytty);	146	=back
		147
		148
		149	=head1 C INTERFACE: THE ptytty FAMILY OF FUNCTIONS
		150
		151	=over 4
		152
		153	=item ptytty_init ()
		154
		155	See C<ptytty::init ()>.
		156
		157	=item PTYTTY ptytty_create ()
		158
		159	Creates a new opaque PTYTTY object and returns it. Do not try to access it
		160	in any way excecp by testing it for truthness (e.g. C<if (pty) ....>). See
		161	C<ptytty::create ()>.
		162
		163	=item int ptytty_pty (PTYTTY ptytty)
		164
		165	Return the pty file descriptor. See C<< pty->pty >>.
		166
		167	=item int ptytty_tty (PTYTTY ptytty)
		168
		169	Return the tty file descriptor. See C<< pty->tty >>.
		170
		171	=item void ptytty_delete (PTYTTY ptytty)
		172
		173	Destroys the PTYTTY object, freeing the pty/tty pair and cleaning up the
		174	utmp/wtmp/lastlog databases, if initialised/used. Same as C<delete pty> in
		175	C++.
		176
		177	=item int ptytty_get (PTYTTY ptytty)
		178
		179	See C<< pty->get >>, returns 0 in case of an error, non-zero otherwise.
		180
50	void ptytty_login (void ptytty, int cmd_pid, bool login_shell, const char hostname);	181	=item void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname)
51		182
		183	See C<< pty->login >>.
		184
52	void ptytty_close_tty (void *ptytty);	185	=item void ptytty_close_tty (PTYTTY ptytty)
		186
		187	See C<< pty->close_tty >>.
		188
53	int ptytty_make_controlling_tty (void *ptytty);	189	=item int ptytty_make_controlling_tty (PTYTTY ptytty)
		190
		191	See C<< pty->make_controlling_tty >>.
		192
54	void ptytty_set_utf8_mode (void *ptytty, int on);	193	=item void ptytty_set_utf8_mode (PTYTTY ptytty, int on)
55		194
56	void ptytty_init ();	195	See C<< pty->set_utf8_mode >>.
57	void *ptytty_create ();
58		196
59	void ptytty_drop_privileges ();	197	=item void ptytty_drop_privileges ()
		198
		199	See C<< ptytty::drop_privileges >>.
		200
60	void ptytty_use_helper ();	201	=item void ptytty_use_helper ()
61		202
62	#endif	203	See C<< ptytty::use_helper >>.
63		204
64	#endif	205	=back
65		206
		207
		208	=head1 BUGS
		209
		210	You kiddin'?
		211
		212	=head1 AUTHORS
		213
		214	Emanuele Giaquinta L<< <e.giaquinta@glauco.it> >>, Marc Alexander Lehmann
		215	L<< <rxvt-unicode@schmorp.de> >>.

Diff Legend

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

Comparing rxvt-unicode/src/libptytty.h (file contents): Revision 1.3 by root, Mon Jan 23 12:05:12 2006 UTC vs. Revision 1.4 by root, Mon Jan 23 12:37:59 2006 UTC

Diff Legend

Comparing rxvt-unicode/src/libptytty.h (file contents):
Revision 1.3 by root, Mon Jan 23 12:05:12 2006 UTC vs.
Revision 1.4 by root, Mon Jan 23 12:37:59 2006 UTC