.TH GNUSERV 1 "" "GNU Emacs Server".UC 4.SH NAMEgnuserv, gnuclient, gnudoit \- Server and Clients for GNU Emacs.SH SYNOPSIS.B gnuclient[-q] [[-h hostname] [-p port] [-r pathname]] [[+line] path] ....br.B gnudoit [-q] [[-h hostname] [-p port]] [sexpr] ....br.B gnuserv.SH DESCRIPTION.PP\fIgnuclient\fP allows the user to request a running GNU Emacs process to editthe named files or directories..PP\fIgnudoit\fP allows the user to request a running GNU Emacs process toevaluate the given arguments inside a progn LISP form..PP\fIgnuserv\fP is the server program that is set running by GNU Emacs to handleall incoming and outgoing requests. It is not usually invoked directly, but isstarted from GNU Emacs by loading the \fIgnuserv\fP package and evaluating the LISP form (gnuserv-start). .SH OPTIONS.TP 8.BI \-qThis option informs both \fIgnuclient\fP and \fIgnudoit\fP to exit onceconnection has been made with the GNU Emacs process. Normally \fIgnuclient\fPwaits until all of the files on the command line have been finished with(their buffers killed) by the GNU Emacs process, and \fIgnudoit\fP normallywaits around for evaluation of its arguments by the GNU Emacs process, andprints the results or error conditions..TP 8.BI \-h " hostname"Used only with Internet-domain sockets, this option specifies the hostmachine which should be running \fIgnuserv\fP.  If this option is notspecified then the value of the environment variable GNU_HOST is usedif set.  If no hostname is specified, and the GNU_HOST variable is notset, an internet connection will not be attempted. N\.B.- \fIgnuserv\fPdoes NOT allow internet connections unless the GNU_SECURE variable hasbeen specified and points at a file listing all trusted hosts. (SeeSECURITY below.).brNote that an internet address may be specified instead of a hostname which canspeed up connections to the server by quite a bit, especially if the clientmachine is running YP..brNote also that a hostname of \fBunix\fP can be used to specify thatthe connection to the server should use a Unix-domain socket (ifsupported) rather than an Internet-domain socket..TP 8.BI \-p " port"Used only with Internet-domain sockets, this option specifies the service portused to communicate between server and clients. If this option is notspecified, then the value of the environment variable GNU_PORT is used, ifset, otherwise a service called ``gnuserv'' is looked upin the services database. Finally, if no other value can be found for theport, then a default port is used which is usually 21490 + uid..brNote that since \fIgnuserv\fP doesn't allow command-line options, the port forit will have to be specified via one of the alternative methods..TP 8.BI \-r " pathname"Used only with Internet-domain sockets, the pathname argument may be needed toinform GNU Emacs how to reach the root directory of a remote machine.\fIgnuclient\fP prepends this string to each path argument given. For example,if you were trying to edit a file on a client machine called otter, whose rootdirectory was accessible from the server machine via the path /net/otter, thenthis argument should be set to '/net/otter'. If this option is omitted, thenthe value is taken from the environment variable GNU_NODE, if set, or theempty string otherwise..TP 8.BI "path"This is the path of the file to be edited. If the file is a directory, thenthe directory browsers dired or monkey are usually invoked instead..TP 8.BI "sexpr"This is part of a GNU Emacs LISP expression to evaluate. All the sexprs areconcatenated together and wrapped in a progn form before sending toGNU Emacs. If no sexpr is supplied on the  \fIgnudoit\fP commandline,\fIgnudoit\fP will read the sexpr to be evaluated from standard input..PP.SH SETUPIf gnuserv was packaged along with your emacs distribution, you shouldbe able to start the server simply by evaluating the GNU Emacs lispform (gnuserv-start).  If that doesn't work, or if you obtainedgnuserv separately from your emacs distribution, copy the filegnuserv.el into a directory on your GNU Emacs load-path. Load it intoGNU Emacs by evaluating the GNU Emacs lisp form (load "gnuserv"). Youshould now be able to start the server by evaluating the lisp form(gnuserv-start). .SH EXAMPLE.RS 4gnudoit -q '(mh-smail)'.brgnuclient -h cuckoo -r /ange@otter: /tmp/*.RE.SH SYSV IPC SysV IPC is used to communicate between \fIgnuclient\fP, \fIgnudoit\fP and\fIgnuserv\fP if the symbol SYSV_IPC is defined at the top of gnuserv.h. Thisis incompatible with both Unix-domain and Internet-domain socket communicationas described below. A file called /tmp/gsrv??? is created as a key for themessage queue, and if removed will cause the communication between server andclient to fail until the server is restarted..SH UNIX-DOMAIN SOCKETSA Unix-domain socket is used to communicate between \fIgnuclient\fP,\fIgnudoit\fP and \fIgnuserv\fP if the symbol UNIX_DOMAIN_SOCKETS is definedat the top of gnuserv.h.  A file called /tmp/gsrvdir????/gsrv is created forcommunication and if deleted will cause communication between server andclient to fail.  Only the user running gnuserv will be able to connect tothe socket..SH INTERNET-DOMAIN SOCKETSInternet-domain sockets are used to communicate between \fIgnuclient\fP,\fIgnudoit\fP and \fIgnuserv\fP if the symbol INTERNET_DOMAIN_SOCKETS isdefined at the top of gnuserv.h. Both Internet-domain and Unix-domain socketscan be used at the same time. If a hostname is specified via -h or viathe GNU_HOST environment variable, \fIgnudoit\fP and \fIgnuclient\fPestablish connections using an internet domain socket. If not,a local connection is attempted via either a unix-domainsocket or SYSV IPC.".SH SECURITYUsing Internet-domain sockets, a more robust form of security is needed thatwasn't necessary with either Unix-domain sockets or SysV IPC..PP\fIgnuserv\fP performs a limited form of security at the machinelevel. By default no internet-domain socket is opened.  If thevariable GNU_SECURE can be found in \fIgnuserv\fP's environment, andit names a readable filename, then this file is opened and assumed tobe a list of hosts, one per line, from which the server will allowrequests. Connections from any other host will be rejected. Even themachine on which \fIgnuserv\fP is running is not permitted to makeconnections unless its hostname is explicitly specified in this file.Note that a host may be either a internet address or a hostname, andthat.I anyuser on an approved host may connect to your gnuserv and execute arbitraryelisp (e.g., delete all your files).If this file contains a lot ofhostnames then the server may take quite a time to start up..SH FILES.PP.TP 8.B /tmp/gsrv???(SYSV_IPC only).TP 8.B /tmp/gsrvdir???/gsrv(unix domain sockets only).TP 8.B ~/.emacsGNU Emacs customization file, see gnu-emacs(1)..SH BUGS.PP Ctrl-D's occurring in gnudoit input strings won't be handled correctly..PP NULs occurring in result strings don't get passed back to gnudoit properly..PP When using SYSV IPC, the maximum allowable sizes of a gnudoit requestand response are governed by the size of the message buffer (definedat compile time). Responses that exceed the maximum allowed size aretruncated..PPLong response strings that result from a gnudoit invocation maysometimes cause the \fIgnuserv\fP process to exit if used with agnu-emacs version 19 release that predates release 23. This is due toa bug in gnu-emacs, so an upgrade to a more recent version will curethe problem. A similar problem may also occur in lucid emacs 19.9, butshould not in later versions..SH AUTHOR.Andy Norman (ange@hplb.hpl.hp.com), based heavily uponetc/emacsclient.c, etc/server.c and lisp/server.el from the GNU Emacs18.52 distribution.