src/pthr_server.h

   1 /* Generic server process.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *
  18  * $Id: pthr_server.h,v 1.4 2002/11/20 14:22:20 rich Exp $
  19  */
  20
  21 #ifndef PTHR_SERVER_H
  22 #define PTHR_SERVER_H
  23
  24 #ifdef HAVE_NETINET_IN_H
  25 #include <netinet/in.h>
  26 #endif
  27
  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
  43  *
  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.
  50  *
  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}.
  54  *
  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}.
  59  *
  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}.
  65  *
  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
  70  * in the logs.
  71  *
  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.
  76  *
  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.
  80  *
  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.
  86  *
  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}!
  92  *
  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.
  98  *
  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.
 106  */
 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);
 122
 123 #endif /* PTHR_SERVER_H */