usage: Print metavariables in SHOUTY letters.

[sw-tools] / src / sw_rsh.h

/* -*-c-*-
 *
 * $Id: sw_rsh.h,v 1.3 2004/04/08 01:52:19 mdw Exp $
 *
 * [Run remote commands *
 * (c) 1999 EBI
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of sw-tools.
 *
 * sw-tools is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * sw-tools is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with sw-tools; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef SW_RSH_H
#define SW_RSH_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Protocol definition -----------------------------------------------*
 *
 * There's a trivial packet protocol used to squeeze various bits of
 * information down the `rsh' or `ssh' connection.  Each packet has a three
 * octet header consisting of a two-octet length and a single octet type.
 * The length is the length of the packet payload, not including the header
 * (which is fetched separately).  The type determines what happens with the
 * payload.
 *
 * There are six packet types defined so far.  These are:
 *
 *   * `args' -- contains a sequence of null-terminated arguments.  The list
 *     stops when there's no more data in the packet.  (The normal
 *     null-terminated-list-of-null-terminated-strings doesn't allow empty
 *     arguments, which are perfectly valid.)
 *
 *   * `env' -- contains a sequence of null-terminated environment variable
 *     assignments of the form `VAR=VALUE'.
 *
 *   * `dir' -- contains a null-terminated path to a current directory.
 *
 *   * `go' -- contains no data.  Means `execute the command now'.
 *
 *   * `data' -- contains data produced by the command.
 *
 *   * `status' -- contains command exit status.  If this is a single octet
 *     then that octet is the exit status; otherwise, it's a null-terminated
 *     signal name.
 *
 * The first four packets are sent from the client to the server; the last
 * two are sent the other way.  The first three packets may be sent in any
 * order, and some may be omitted.  (This doesn't happen in the current
 * implementation.)
 *
 * The command was already sent as the `--remote' argument to the remote
 * `sw'.
 *
 * (There's also a fake packet type used for representing eof on the stream.
 * This should never be seen on the wire -- it's only for internal use.)
 */

/*----- Data structures ---------------------------------------------------*/

/* --- Packet type codes --- */

enum {
  PKTYPE_EOF,				/* Fake end-of-file condition */
  PKTYPE_ARGS,				/* Argument array */
  PKTYPE_ENV,				/* Environment array */
  PKTYPE_DIR,				/* Current directory */
  PKTYPE_GO,				/* You have all you need to know */
  PKTYPE_DATA,				/* Here's some data */
  PKTYPE_STATUS,			/* My job ended: here's why */
  PKTYPE_BOGUS				/* Bogus packet type */
};

#define PKMAX 4096			/* Maximum packet size */

/* --- A `remote context' --- *
 *
 * Describes everything there is to know about a remotely executing job.
 *
 * Note that `fdin' and `fdout' are identical on the local side, and
 * (potentially) different on the remote side.  Be careful!
 */

typedef struct sw_remote {
  int fdin, fdout;			/* File descriptors */
  size_t sz;				/* Size of data in buffer */
  char buf[PKMAX + 1];			/* Input buffer (handy for output) */
} sw_remote;

/* --- A remote command definition --- *
 *
 * Like normal user commands, these are linked into a list.  See `sw.h' for
 * the nitty-gritty.  The magic link macro is called @RCMD_LINK@.
 */

typedef struct rcmd {
  struct rcmd *next;
  const char *name;
  void (*rcmd)(sw_remote */*r*/, char */*argv*/[], char */*env*/[]);
} rcmd;

/*----- Packet interface --------------------------------------------------*/

/* --- @pksend@ --- *
 *
 * Arguments:	@sw_remote@ = pointer to the remote block
 *		@int type@ = packet type to send
 *		@const void *p@ = pointer to packet data
 *		@size_t sz@ = size of data to send
 *
 * Returns:	Zero if it worked, nonzero otherwise.
 *
 * Use:		Sends a data packet.  If the type is `data', then `sz' may be
 *		arbitrarily large and is divided into small enough chunks.
 *		Otherwise it's an error to send a packet that's too big.
 */

extern int pksend(sw_remote */*r*/, int /*type*/,
		  const void */*p*/, size_t /*sz*/);

/* --- @pkrecv@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote block
 *
 * Returns:	Packet type received, or @-1@ for an error.
 *
 * Use:		Receives a packet from the remote host.  The packet data is
 *		placed in the block's buffer, the block's packet length is
 *		diddled appropriately.
 */

extern int pkrecv(sw_remote */*r*/);

/*----- Error reporting and exit statuses --------------------------------*/

/* --- @swexit@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote context
 *		@int status@ = exit status to return
 *
 * Returns:	Doesn't.
 *
 * Use:		Reports the exit status via packet protocol and quits.
 */

extern void swexit(sw_remote */*r*/, int /*status*/);

/* --- @swsignal@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote context
 *		@int sig@ = signal ocurrence to return
 *
 * Returns:	Doesn't.
 *
 * Use:		Reports a signalled-to-death status via packet protocol and
 *		quits.
 */

extern void swsignal(sw_remote */*r*/, int /*sig*/);

/* --- @swwait@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote context
 *		@int status@ = status answer from @wait@(2)
 *
 * Returns:	Doesn't.
 *
 * Use:		Reports a child's demise appropriately, and quits.
 */

extern void swwait(sw_remote */*r*/, int /*status*/);

/* --- @swvprintf@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote context
 *		@const char *format@ = format string
 *		@va_list ap@ = things to format
 *
 * Returns:	---
 *
 * Use:		Writes a string to the remote end.  This is the low-level bit
 *		of @swprintf@.
 */

extern void swvprintf(sw_remote */*r*/,
		      const char */*format*/, va_list /*ap*/);

/* --- @swprintf@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote context
 *		@const char *format@ = format string
 *		@...@ = other arguments
 *
 * Returns:	---
 *
 * Use:		Writes a string to the remote end.
 */

extern void swprintf(sw_remote */*r*/, const char */*format*/, ...);

/* --- @swdie@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote context
 *		@int status@ = exit status to report
 *		@const char *format@ = format string to fill in
 *		@...@ = other arguments
 *
 * Returns:	Doesn't.
 *
 * Use:		Reports a message and quits.
 */

extern void swdie(sw_remote */*r*/, int /*status*/,
		  const char */*format*/, ...);

/*----- Remote invocation -------------------------------------------------*/

/* --- @swrsh_remote@ --- *
 *
 * Arguments:	@const char *cmd@ = the command to perform
 *
 * Returns:	Doesn't.  Reports an exit status through packet protocol and
 *		quits.
 *
 * Use:		Handles the remote end of a remote job invokation.
 */

extern void swrsh_remote(const char */*cmd*/);

/*----- Starting remote jobs ----------------------------------------------*/

/* --- @swrsh@ --- *
 *
 * Arguments:	@sw_remote *r@ = remote process block to look after
 *		@const char *host@ = host to run on (0 for this one)
 *		@const char *cmd@ = remote command to run
 *		@char *argv[]@ = arguments to pass on
 *
 * Returns:	Zero if it worked, nonzero if not.
 *
 * Use:		Runs a command on a remote host.  The argument array is
 *		mangled to come out OK at the far end.  The environment and
 *		current directory are also passed along, and pop out the
 *		other end unmolested.
 */

extern int swrsh(sw_remote */*r*/, const char */*host*/,
		 const char */*cmd*/, char */*argv*/[]);

/*----- Subcommands -------------------------------------------------------*/

extern void rsw_rsh(sw_remote */*r*/, char */*argv*/[], char */*env*/[]);
extern int sw_rsh(int /*argc*/, char */*argv*/[]);

#ifdef CMD_LINK
   static cmd cmd_rsh = {
     CMD_LINK, "rsh", sw_rsh,
"rsh HOST|ARCH COMMAND [ARGS...]\n\
	Runs the COMMAND on the remote host HOST (or one which supports\n\
	architecture ARCH), passing it the given ARGS.	Note that the\n\
	command and arguments aren't subject to	shell expansions on the\n\
	remote site (unlike with `rsh').  Environment variables are passed\n\
	on to the remote command, as is the current directory.  The\n\
	environment variable `SW_RSH' contains the name of a remote-shell\n\
	program to start up the remote command (`rsh' and `ssh' work\n\
	well); " RSH " is used by default.  The magic hostname `-'\n\
	refers to the local machine, as does the current host's\n\
	architecture name.  In these cases, the command is run directly.\n"
   };
#  undef CMD_LINK
#  define CMD_LINK &cmd_rsh
#endif

#ifdef RCMD_LINK
   static rcmd rcmd_rsh = { RCMD_LINK, "rsh", rsw_rsh };
#  undef RCMD_LINK
#  define RCMD_LINK &rcmd_rsh
#endif

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif