1 /* Generic server process.
2 * - by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: pthr_server.h,v 1.4 2002/11/20 14:22:20 rich Exp $
24 #ifdef HAVE_NETINET_IN_H
25 #include <netinet/in.h>
28 /* Function: pthr_server_main_loop - Enter server main loop.
29 * Function: pthr_server_default_port
30 * Function: pthr_server_port_option_name
31 * Function: pthr_server_default_address
32 * Function: pthr_server_address_option_name
33 * Function: pthr_server_disable_syslog
34 * Function: pthr_server_package_name
35 * Function: pthr_server_disable_fork
36 * Function: pthr_server_disable_chdir
37 * Function: pthr_server_disable_close
38 * Function: pthr_server_chroot
39 * Function: pthr_server_username
40 * Function: pthr_server_stderr_file
41 * Function: pthr_server_startup_fn
42 * Function: pthr_server_enable_stack_trace_on_segv
44 * The function @code{pthr_server_main_loop} is a helper function which
45 * allows you to write very simple servers quickly using @code{pthrlib}.
46 * Normally your @code{main} should just contain a call to
47 * @code{pthr_server_main_loop (argc, argv, processor)}
48 * and you would include a function called @code{processor} which is
49 * called on every connection.
51 * The other functions allow you to customise the behaviour of
52 * @code{pthr_server_main_loop}. You should call any of these once
53 * in your @code{main} before calling @code{pthr_server_main_loop}.
55 * By default the server listens on port 80 and allows you to
56 * override this on the command line using the @code{-p} option.
57 * To change this, call @code{pthr_server_default_port} and/or
58 * @code{pthr_server_port_option_name}.
60 * By default the server listens on address INADDR_ANY (all local
61 * addresses) and allows you to override this on the command line
62 * using the @code{-a} option. To change this, call
63 * @code{pthr_server_default_address} and/or
64 * @code{pthr_server_address_option_name}.
66 * By default the server writes package and version information to
67 * syslog (although it will not be able to correctly determine the
68 * package). Use @code{pthr_server_disable_syslog} to disable syslogging
69 * entirely, or @code{pthr_server_package_name} to change the name displayed
72 * By default the server forks into the background, changes to the
73 * root directory and disconnects entirely from the terminal. Use
74 * @code{pthr_server_disable_fork}, @code{pthr_server_disable_chdir} and
75 * @code{pthr_server_disable_close} to change these respectively.
77 * If you wish to have the server chroot after start up, then call
78 * @code{pthr_server_chroot}. This is only possible if the server
79 * is run as root, otherwise the chroot is silently ignored.
81 * If you wish to have the server change user and group after start up,
82 * then call @code{pthr_server_username} (the group is taken from
83 * the password file and @code{initgroups(3)} is also called). This
84 * is only possible if the server is run as root, otherwise the
85 * change user is silently ignored.
87 * If you wish to have @code{stderr} connected to a file (this is done after
88 * changing user, so make sure the file is accessible or owned by the
89 * user, not by root), then call @code{pthr_server_stderr_file}. Note
90 * that unless you call this function or @code{pthr_server_disable_close}
91 * then @code{stderr} is sent to @code{/dev/null}!
93 * The @code{startup_fn} is called after all of the above operations
94 * have completed, but before the listener thread is created. You
95 * do miscellaneous start-of-day functions from here, in particular
96 * starting up other global threads. The command line arguments are also
97 * passed to this function.
99 * If @code{pthr_server_enable_stack_trace_on_segv} is called, then
100 * the server will attempt to dump a full stack trace to @code{stderr}
101 * if it receives a @code{SIGSEGV} (segmentation fault). This is useful
102 * for diagnosis of errors in production systems, but relies on some
103 * esoteric GLIBC functions (if these functions don't exist, then this
104 * setting does nothing). If the executable is linked with @code{-rdynamic}
105 * then symbolic names will be given in the stack trace, if available.
107 extern void pthr_server_main_loop (int argc, char *argv[], void (*processor_fn) (int sock, void *));
108 extern void pthr_server_default_port (int default_port);
109 extern void pthr_server_port_option_name (char port_option_name);
110 extern void pthr_server_default_address (in_addr_t default_address);
111 extern void pthr_server_address_option_name (char address_option_name);
112 extern void pthr_server_disable_syslog (void);
113 extern void pthr_server_package_name (const char *package_name);
114 extern void pthr_server_disable_fork (void);
115 extern void pthr_server_disable_chdir (void);
116 extern void pthr_server_disable_close (void);
117 extern void pthr_server_chroot (const char *root);
118 extern void pthr_server_username (const char *username);
119 extern void pthr_server_stderr_file (const char *pathname);
120 extern void pthr_server_startup_fn (void (*startup_fn) (int argc, char *argv[]));
121 extern void pthr_server_enable_stack_trace_on_segv (void);
123 #endif /* PTHR_SERVER_H */