#!/bin/sh # shar: Shell Archiver # Run the following text with /bin/sh to create: # vxRsh.man # vxRsh.h # This archive created: Tue Aug 27 11:13:26 1991 echo shar: extracting vxRsh.man '(8943 characters)' cat << \SHAR_EOF > vxRsh.man vxRsh(4) VxWorks Reference Manual vxRsh(4) NAME vxRsh.c - vxRsh client source SYNOPSIS vxRsh [-t] [-b] vxRsh [-t] [-l ] [-e] [-r] [-s] vxRsh [-h] DESCRIPTION vxRsh is a client server model based on text protocol. It is designed to enable remote execution of vxWorks commands from UNIX host. vxRsh typically uses the vxWorks shell for the remote execution however, by using the [-b] option the shell is bypassed. Bypassing the shell is essential to overcome the fact that the shell is not reentrant. In both cases (using or bypassing the shell) the STDOUT of the target is redirected to the connecting socket. vxRsh can also be used to log and filter the STDOUT of vxWorks to a UNIX file. Other features include hard and soft reset to a vxWorks target and a report of the peer name connected to the target locking the shell (e.g. rlogin, tel- net). It requires a vxRshd server to run on the a vxWorks target. A subset of vxRsh can run on vxWorks. OPTIONS [-b] Bypass target shell. The default of the server is to execute by passing to execute(2). Due to the fact that the shell is not reentrant, it implies that only one shell session can be active at the same time. The [-b] option is an alternative: the vxRshd receives the command, parses it and then activates a routine which corresponds to the first string in . By no means is this parsing as powerful as the vxWorks shell. For example you can not defined a new variable. The only format which is sup- ported is: [ [[,] ...]] Where can be either a symbol or a number or a string (surrounded by quotes). Up to ten parameters are supported. Still, it should cover many cases. Note that vxWorks has a global STDOUT for all tasks. Using the [-b] option can be confusing to other tasks (e.g. active rlogin). Thus, it is recommended to use this option only for commands which take short execu- tion time (you can always spawn a new task). Version 5.0 - 27 aug 91 1 vxRsh(4) VxWorks Reference Manual vxRsh(4) [-e] Stop log file. This option stops any active log ses- sion started with [-l] option. It can be useful when there is a confusion about where STDOUT is at a par- ticular time. [-h] Prints the usage message [-l] Start log file. is used as a generic file name. The generic name is augmented with a string con- sisting of the month and day: (e.g. foo_Aug_22). vxRsh keeps writing all the shell standard output to this file. Each line is prefixed with the time stamp (client's local time). Once the server detects that the day has changed, the current log file is closed and a new file is opened. The code for this function is hidden in vxRshSetLine(2) and should be easy to customize. Note that if is "" the server dumps the output to it's STDOUT. The vxWorks shell must be unlocked when the logging is triggered. Thereafter, it can be locked or unlocked. Note that whenever the STDOUT is redirected (e.g rlo- gind) the logging stops. It resumes automatically after the redirection is restored (i.e. logout). Any new activation of [-l] option closes the previous log session (if it exists) and starts a new log ses- sion. One possible usage of this option is to start the client in the boot script of the target. This will ensure constant monitoring of the shell into a file (except for STDOUT redirection). In case of confusion about STDOUT you can always res- tart the shell and reinitialized STDOUT by heating control/c. [-r] Target reset - hardware reset. Typically, the server calls a special BSP routine (HW reset) which rests the board. If your board does not support HW reset set the DEFINE flags in vxRsh.h to call reboot(BOOT_COLD). Note that the shell is not needed for this option and no questions are asked... [-s] Target reset - software reset. Typically, the server calls reboot(BOOT_WARM_QUICK_AUTOBOOT). The shell is not required for this option. (i.e. It can be called even if the shell is locked e.g. rlogin). [-t] Enables timeout for read/write socket operations when communicating with the server. This option can be use- ful when the target must response within a predefined time. The default for this option is OFF. [-t] Enables Version 5.0 - 27 aug 91 2 vxRsh(4) VxWorks Reference Manual vxRsh(4) timeout. [-w] Find the peer name that is locking shell (typically via rlogin or telnet). The server checks all the open file descriptors for a valid connected socket. The first socket found, is assume to be the one which is "engaged". The server decodes it's peer IP address. The client uses it's local data base to translate the IP address into a host name. This approach is neither "clean" nor suitable. However, it is less embracing than having a target connected from unknown loca- tion... It is possible to control the search in the FD table by modifying VXRSH_SEARCH_PEER_[LOW|HIGH] in vxRsh.h. COMPATIBILITY This tool is based on the execute(2) routine. In vxWorks 4.0.1 this routine was defined as static. It is extern in 5.X. If your version does not allow linking to execute(2), you can either disable the "session" option by bypassing the shell or decode the address from the disassembler... The vxRsh client runs on UNIX host and on vxWorks target. How- ever, the vxWorks version of the client is only a subset of the UNIX version. Currently, the server runs on vxWorks target only. RETURN The client returns one of the following values (These values are defined in vxRsh.h): [VXRSH_ERR_OK] No errors - Normal termination. [VXRSH_ERR_SYNTAX] Illegal syntax. [VXRSH_ERR_OPEN] Can not establish connection. [VXRSH_ERR_IO] Can not read or write. [VXRSH_ERR_INUSE] Target is already in use. [VXRSH_ERR_EXEC] Remote execution error. [VXRSH_ERR_ABORT] Operation aborted (e.g. ^C). [VXRSH_ERR_DECODE] Unable to decode return value. [VXRSH_ERR_TO] Time out error. [VXRSH_ERR_CLIENT_CMD] Illegal client protocol command. [VXRSH_ERR_CLIENT_EXEC] Client execution error. [VXRSH_ERR_TARGET] Target returns ERROR (-1). When called from a UNIX shell this value is assigned to a UNIX shell variable (e.g. $?). A special case is when the target returns: "Sorry, this system is engaged". Version 5.0 - 27 aug 91 3 vxRsh(4) VxWorks Reference Manual vxRsh(4) For this case the server returns the IP address of the peer which is locking the shell (see above [-w]). EXAMPLES To execute the command "i" on beethoven (target name): vxRsh beethoven i Find who is logged to beethoven vxRsh -w beethoven To send a string (note that \" escaping might depend on your (UNIX) shell): vxRsh beethoven "printf \"Hello world\"" To start logging the target STDOUT into a file stam_MMM_DD: vxRsh -l stam beethoven To stop logging the target STDOUT: vxRsh -e beethoven Bypass the target: vxRsh -b beethoven ls And finally to hardware reset the target: vxRsh -r beethoven BUS vxRsh is not compatible with the standard UNIX rsh. The search for the peer which is locking the vxWorks shell should be part of shellLib(1). AUTHORS Benny Schnaider: benny@vlss.amdahl.com (408) 746-3440 SEE ALSO vxRshd(2) vxRsh.h Version 5.0 - 27 aug 91 4 SHAR_EOF if test 8943 -ne "`wc -c vxRsh.man`" then echo shar: error transmitting vxRsh.man '(should have been 8943 characters)' fi echo shar: extracting vxRsh.h '(4171 characters)' cat << \SHAR_EOF > vxRsh.h /* * vxRsh.h * * HISTORY: * 09/01/89 Benny Schnaider: Created. */ #define VXRSH_PORT_NUM 1112 #define VXRSH_PRIORITY 90 #define VXRSH_STACK_SIZE 12000 #define SHELL_STACK_SIZE 10000 #define BUFF_LEN 512 #define VXRSH_TO 20 #define VXRSH_VAR "VXRSH_VALUE" /* Environemt variable for */ /* returns values from the */ /* target. */ #define VXRSH_CMD_OPTIONS "behl:rstw" /* Command option for vxRsh */ #define FILE_NAME_LENGTH 100 /* For log files */ /* * Compile directives */ #ifdef NEVER_DEF #define VXRSH_DEBUG /* For module debugging */ #define VXRSH_RESET /* BSP support HW reset i.e., reset() */ #define VXRSH_VXWORK_4.X /* Define this if you can NOT link to execute */ #endif /* NEVER_DEF */ #define VXRSH_TEST /* For model testing */ #define VXRSH_SP /* Spawn each command and wait for new connections */ #ifndef OK #define OK 0 #endif /* OK */ #ifndef ERROR #define ERROR -1 #endif /* ERROR */ #ifndef LOCAL #define LOCAL static #endif /* LOCAL */ #ifndef STATUS #define STATUS int #endif /* STATUS */ /* * Return codes. * The return codes can be read by using the default retun value from the * Shell. If the value is OK (0) the actual value return from the target * can be read from shell VXRSH_VAR varaible. */ #define VXRSH_ERR_OK 0 /* No errors */ #define VXRSH_ERR_SYNTAX 1 /* Illegal syntax */ #define VXRSH_ERR_OPEN 2 /* Can not establish connection */ #define VXRSH_ERR_IO 3 /* Can not read or write */ #define VXRSH_ERR_INUSE 4 /* Traget is already in use. */ #define VXRSH_ERR_EXEC 5 /* Remote execution error */ #define VXRSH_ERR_ABORT 6 /* Operation aborted */ #define VXRSH_ERR_DECODE 7 /* Unable to decode return value */ #define VXRSH_ERR_TO 8 /* Time out error */ #define VXRSH_ERR_CLIENT_CMD 9 /* Illegal client protocol command */ #define VXRSH_ERR_CLIENT_EXEC 10 /* Cleint execution error */ #define VXRSH_ERR_TARGET 20 /* Target returns ERROR (-1) */ #define VXRSH_SEARCH_PEER_LOW 4 #define VXRSH_SEARCH_PEER_HIGH 12 /* * Commands * This are primitive commands send from the server to the client at * the begining of the session. */ #define VXRSH_CMD_START_LOG "SLG" /* Start log file */ #define VXRSH_CMD_END_LOG "ELG" /* End log file */ #define VXRSH_CMD_HW_RESET "HRS" /* Hardware reset */ #define VXRSH_CMD_SW_RESET "SRS" /* Software reset */ #define VXRSH_CMD_SESSION "SES" /* vxRsh seesion - like rshd */ #define VXRSH_CMD_BYPASS "BPS" /* Bypass vxWorks shell */ #define VXRSH_CMD_WHO "WHO" /* Find who is locking the shell */ #define VXRSH_CMD_LEN 3 /* 3 char per command lexim */ #define VXRSH_MAX_CMD_ARG 11 /* Do not touch it unless you modify * /* the code */ /* * External routines */ extern vxRsh(/* hostName, command, protocolCommand */); /* **********************************************************/ /* char *hostName; */ /* Target name */ /* char *command; */ /* VxWorks shell command */ /* char *protocolCommand; */ /* e.g. VXRSH_CMD_SESSION */ extern void vxRshFilterLine(/* inBuff */); /* *********************************************/ /* char *inBuff; */ /* Input buffer */ extern vxRshd(); /* *******************/ extern STATUS vxRshdInit(/* stackSize */); /* *********************************************/ /* int stackSize; */ /* Stack size to be used for the server */ extern void vxRshdTest(); /* ****************************/ extern STATUS vxRshConnectWho(/* buffIn, rangeLow, rangeHigh */); /* ********************************************************************/ /* char *buffIn; */ /* Output buffer */ /* int rangeLow; */ /* Lower limit for FD search */ /* int rangeHigh; */ /* Higher limit for FD search */ SHAR_EOF if test 4171 -ne "`wc -c vxRsh.h`" then echo shar: error transmitting vxRsh.h '(should have been 4171 characters)' fi # End of shell archive exit 0