-------------------------------------------------------------------------------
NETSCRIPT: documentation support on syntax, ruleset, and environment help.
AUTHOR: v9@fakehalo.deadpig.org, fakehalo.deadpig.org. [ihadnihn]
TOC: syntax, ruleset, environment, module, security, eof.
-------------------------------------------------------------------------------


             __                _       __
  _ __   ___| /_ ___  ___ _ __(_)_ __ | /_  (portable/multi-platform) lightwei-
 | '_ \./ _ \ __/ __)/ __| '__| | '_ \| __) ght tcp/udp socket scripting.  int-
 | | | |  ._/ |_(__ \ (__| |  | | |_) ) |_  ended for (non-)experienced person-
 |_| |_|\___|\__|___/\___|_|  |_| .__/ \__) s to be able to use to automate si-
 [TCP / UDP socket scripting] |_| [1.7.1]   tuations, built on a word-to-word
                                            ruleset response system.  includes
 wildcard support, character replacement, random replacement, argument inclusi-
 on, server timeout, initial send, display altering, multiple character dump f-
 ormats, telnet protocol support, logging, program to socket dumping, executab-
 le ruleset support, reverse binding, module support, data truncation, data fo-
 rmatting, permission options, virtual hosting support, history storage, dynam-
 ic storage variables, directory placement, character omitting, timed rules, b-
 ackground support, syslog support, routing support, socket options, interacti-
 ve mode, and a graphical user interface among other things.


******************
***** SYNTAX *****
******************

there are a good amount of command line options for netscript.  so, they need
some sort of explaination. (minimal as it may seem)

NOTE: the required arguments to run are: -r or -s or -f, -h or -b, and -p.

 -r <argument>
     this will take the supplied argument as the ruleset file.

 -h <argument>
     this will take the supplied argument as the hostname, or ip to connect to.
     (if you use commas it will connect to each remote host in order.  example:
     ./netscript -r rules -h server1.com,server2.com -p 1)

 -p <argument>
     this will take the supplied argument as the port to connect to, or bind
     as.  also, you may use services defined in /etc/services as ports.  for
     example: "finger", "http", and "ftp".

 -# <data>
     will statically define the dynamic variable.  storing the following data
     in ${#}, and making it an unchangeable variable. (# = a value between 0-9)

 -i <argument>
     this will take the supplied argument as initial data to send to the remote
     host once connected.  also, if a "?" is used as the argument it will take
     dynamic information from standard input once connected.

 -m <argument>
     this will change the current working directory of netscript to the
     supplied argument.  this is handled before anything else. (except -M)

 -M <argument>
     this will change the root directory of netscript to the supplied argument.
     this is handled before anything else. (superuser only.  also note, this
     will severely cripple netscript, use only under special circumstances)

 -R <argument>
     this will take the supplied argument as a route hostname, or ip to use.
     this means information that occurs on the main connection will be passed
     over to this hostname/ip.  the virtual hostname(-q option), if defined,
     will be applied to this option.  also note, if the connection is dropped,
     it will not notify, it will remain silent(unless done via a ruleset
     request). (this function only connects out)

 -k <argument>
     this will take the supplied argument as a port to connect to on the route
     hostname/ip.

 -u <argument>
     this will change the id permissions of netscript(uid/gid/groups).  the
     format is "user[.group]".  but, if just "user" is supplied it will work,
     it will just use the group id of the user id.  the id permissions change
     right after a successful connection.  but, set before taking any input, or
     sending any output. (this will not conflict with privileged running of
     netscript, security would still remain)

 -q <argument>
     this will take the supplied argument as a virtual hostname, or ip to use.
     (note: this has priority over the environmental variable usage)

 -o <argument>
     this will take the supplied argument as a set of character(s) to omit from
     socket reading. (will omit the characters before any contact, at the same
     level as the -P option)

 -S <argument>
     this will wait the alloted time supplied by the argument before processing
     incoming data.  can be used in conjunction with -U. (in seconds)

 -U <argument>
     this will wait the alloted time supplied by the argument before processing
     incoming data.  can be used in conjunction with -S. (in useconds)

 -t <argument>
     this will close the session after the alloted time supplied by the
     argument, the countdown starts once conncted to the server.

 -Q <argument>
     this will take the supplied argument to set socket option(s) within
     netscript.  the format for this option is "value1,value2,value3" separated
     by a colon, for multiple socket options.  the first value is for the
     socket used, to apply the option to the socket; 0 is for the connecting
     in/out socket(client socket).  1 is for the binded socket(server socket).
     2 is for the route socket(-R option).  the second value is for the option
     itself(options are listed below).  the third, and final value is to set
     the value of the second value.

     here is a generalized list of values that can be used for the socket
     option(second value used): 1=SO_DEBUG, 2=SO_REUSEADDR, 3=SO_TYPE,
     4=SO_ERROR, 5=SO_DONTROUTE, 6=SO_BROADCAST, 7=SO_SNDBUF, 8=SO_RCVBUF,
     9=SO_KEEPALIVE, 10=SO_OOBINLINE, 11=SO_NO_CHECK, 12=SO_PRIORITY,
     13=SO_LINGER, 14=SO_BSDCOMPAT, 15=SO_REUSEPORT, 16=SO_PASSCRED,
     17=SO_PEERCRED, 18=SO_RCVLOWAT, 19=SO_SNDLOWAT, 20=SO_RCVTIMEO,
     21=SO_SNDTIMEO.

     for example, "-Q 1,2,1:1,15,1" would have the following effect in C:
     {
      int i=1;
      setsockopt(bindsocketfd, SOL_SOCKET, SO_REUSEADDR, &i, sizeof(i));
      setsockopt(bindsocketfd, SOL_SOCKET, SO_REUSEPORT, &i, sizeof(i));
     }
     if this example displays the error message "internal setting of socket
     option failed", the system probably does not support SO_REUSEPORT.

     note: this option will not support all socket options, only socket options
     that are intended to be used in enabled/disabled, or numeric situations.
     considering this option only passes values in the form of an integer.

 -l <argument>
     this will take the supplied argument as a file to log input/output data.

 -G <argument>
     this will display the argument as the title for the gui.  this is for use
     with gui mode.

 -+ <argument>
     this will take the argument as a value to change the length of the
     pulled down gui.  this is for use with the non-generic gui only.

 -# <argument>
     this will take the argument as a hex triplet to set as the color of the
     foreground text, for use with gui mode. ("#" precursor is not needed)

 -K <argument>
     this will define alternate button labels for the netscript gui.  the
     argument format is "label1:label2:label3"; where "label1" is the exit
     button, "label2" is the clear screen button, and "label3" is the pulldown
     check button(only in non-generic gui).  this is for use with the gui mode.

 -= <argument>
     this will define alternate button tabs for the netscript (ncurses) gui.
     the argument format is "label1:label2"; where "label1" is the output tab,
     and "label2" is the input tab.  this is for use with the (ncurses) gui
     mode. (this is optional upon compile)

 -e <argument>
     this will take the supplied argument as a program to dump to the remote
     host once connected.

 -E <argument>
     precurse data to attach for each line dumped.  this works in conjuntion
     with the -e option, and the $= variable.

 -O <argument>
     this will use an alternate shell to execute third party programs.  it
     will override that of the $SHELL environmental variable, or the default.

 -x <argument>
     this will kill the program if the dumping of the program supplied with the
     -e option exceeds the time allowed(idle time) with the supplied argument.
     (3 is the internal default)

 -X
     this will kill netscript after the dumping of the program to the remote
     host.

 -a
     this will allow interactive use of programs. (if you use this, be on guard
     of what you are doing)

 -f
     this will launch a third party editor to make a temporary ruleset.  if
     the -r option is used in conjunction with -f, it will take that file as
     a ruleset to edit, instead of a temporary file.  it will not remove the
     file upon completion, if the -r option is used.

 -@
     this will switch netscript to the UDP protocol.  this may, or may not
     effect the performance of netscript.  since connections do not actually
     exist, the connection will never be dropped unless invoked via the
     ruleset. (the UDP protocol allows for packet loss)

 -^
     this will switch the route host to the UDP protocol.

 -B
     sends netscript to the background. (forked)

 -n
     this will disable display of any outgoing data, will not effect logging.

 -N
     this will disable display of any incoming data, will not effect logging.

 -j
     this will disable routed sending of outgoing data. (route support)

 -J
     this will disable routed sending of incoming data. (route support)

 -F
     this will disable display of the arrow precursors, will not effect
     logging.

 -I
     this will reocnnect to the remote host, or rebind to the port specified.
     when disconnected.

 -s
     this will take the ruleset from standard input, instead of a file.

 -b
     this will bind to the supplied port instead of connecting out, like a
     reversed mode.

 -g
     enables the gui frontend of netscript, once launched. (use twice for
     generic version)  also, if launched via a link from ./gnetscript,
     netscript will automatically apply the -g option.

 -W
     this will automatically start the (non-generic) gui pulled down.

 -_
     this will switch the console display of netscript to ncurses.
     also, if launched via a link from ./nnetscript, netscript will
     automatically apply the -_ option. (this is optional upon compile)

 -Z
     system logging support, for when netscript is running at a syslog
     accessible level.  this will log initialization, execution of third party
     programs, reading of files, writing to files, ip/port, id changes, and
     exit notification. (the pid shown in the syslog line will be the main pid,
     even if it is not the current pid running that logged the line, this will
     help to keep information together by reference of the pid)

 -T
     this will attempt to reply to telnet option requests.  this will also
     change the handling of incoming data if turned on, and has received one,
     or more telnet option(s).

 -y
     will dump raw socket data to standard error.  this is for use with the
     telnet option(-T).  it will dump the raw incoming, and outgoing socket
     data in an effort to correct segment breaking.  it will not change the
     effects it has on the ruleset, it will still handle in segments. (this
     will force other options to be disabled, and/or enabled.  this includes
     having telnet mode(-T) on.  also, this will override normal logging
     routines)

 -Y
     will dump raw socket data to standard output.  this is for use with the
     telnet option(-T).  it will dump the raw incoming, and outgoing socket
     data in an effort to correct segment breaking.  it will not change the
     effects it has on the ruleset, it will still handle in segments. (this
     will force other options to be disabled, and/or enabled.  this includes
     having telnet mode(-T) on.  also, this will override normal logging
     routines)

 -z
     this will disable display for telnet option replies, with the -T option.

 -L
     displays the value of each line as a precursor. (this option will force
     disabled word wrapping)

 -H
     this will display input/output in hex form, instead of character form.

 -D
     this will display input/output in decimal form, instead of character form.

 -w
     this will disable wordwrap support for input/output displaying.

 -P
     this will disable reading of non-printable characters from the socket, the
     -T option is processed before this, so it will be un-effected.

 -c
     this will disable the display of initial connection notification
     information.

 -C
     this will disable the display of ruleset information that is not required
     to know. (basically, this cuts down on excess screen junk)

 -A
     this will disable the display of all netscript prompts containing
     information. (for example, "./netscript: so, and so." will not be shown)

 -d
     this will display a shortened definition list of ruleset variables, and
     environmental variables used with netscript.

 -v
     this will display the version, and id value of netscript(format 1) and
     exit.

 -V
     this will display the version, and id value of netscript(format 2) and
     continue.

 --list [argument:argument:...] (must be the first, and only argument used)
     this option is for use with command line use only.  lists, and allows
     usage of ruleset(s) via a file list.  the argument(s), if supplied,
     will be taken as alternative directory(s) to list, instead of the current
     working directory.

 --hist [argument] (must be the first, and only argument used)
     this option is for use with command line use only.  lists, and allows
     usage of past arguments from the netscript history file. (~/.nshistory)
     if an argument is provided it will be taken as the history line value to
     use for arguments.  but, if the argument provided is "clear" it will
     delete the history file, if it exists. (use $20/$032's for spaces on most
     parameters to avoid issues with multi-space arguments, when using
     netscript in general)


*******************
***** RULESET *****
*******************

netscripts ruleset, the whole point of netscript, is to check for given input
from the server that matches the input in the ruleset.  the structure of the
ruleset is a simple per-line format, one line for input, and one for output.
this is illustrated like so:

file.ruleset:
-------------------------------------------------------------------------------
# example of basic ruleset.
input given 1
output responded 1
input given 2
output responded 2
-------------------------------------------------------------------------------

if this ruleset was used it would respond "output responded 1" if "input given
1" was sent to the socket, and "output responded 2" if "input given 2" was sent
to the socket.  this ruleset is a direct match situation.

if you want to be able to run the ruleset +x/executable, you can format the
ruleset like so:

file.ruleset:
-------------------------------------------------------------------------------
#!/path/to/netscript
#?-h host.com -p 1
# example of basic ruleset.
input given 1
output responded 1
input given 2
output responded 2
-------------------------------------------------------------------------------

"#!"(on the first line) followed by the direct path to netscript, and
"#?"(on the second line) followed by the arguments desired will use the
supplied information as netscript arguments.  then you can chmod +x the
ruleset to run it.

if information being received may not be a static value you can use match
variables to check for matches with data from there remote host, here is the
list of variables that can be used, with an explaination:

NOTE: these are ONLY for use with input responses, not output.  also, these
match variables require a word slot to use correctly(spaces in-between).


 "$;" (must be the first data on the output line, needs data)
     when this is placed at the beginning of the line it will allow a match,
     as long as what is placed after the variable does not match the incoming
     data.

     example:
      $;001 $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by anything, or nothing the ruleset would not send "USER test".
     (it will only send if it did not match)


 "$*"
     when this is placed at the end of the line(with a space before) it will
     allow a match as long as anything before its use matched.

     example:
      001 $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by anything, or nothing the ruleset would send "USER test".


 "$?"
     when this is placed at the end of the line(with a spaces) it will
     allow a match as long as input has a value, and isn't non-existent.

     example:
      001 $? $? $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by two, or more words the ruleset would send "USER test".


 "$ALPHA"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is alphabetical. (A-Za-z)

     example:
      001 $ALPHA $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by an alphabetical word the ruleset would send "USER test".


 "$DIGIT"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is numerical. (0-9)

     example:
      001 $DIGIT $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by a numerical word the ruleset would send "USER test".


 "$ALNUM"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is alphabetical, or numerical.
     (A-Za-z0-9)

     example:
      001 $ALNUM $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by an alphabetical, or numerical word the ruleset would send
     "USER test".


 "$UPPER"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is upper case. (A-Z)

     example:
      001 $UPPER $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by a upper case word the ruleset would send "USER test".


 "$LOWER"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is lower case. (a-z)

     example:
      001 $LOWER $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by a lower case word the ruleset would send "USER test".


 "$PUNCT"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is printable/non-standard.

     example:
      001 $PUNCT $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by a punctuated word the ruleset would send "USER test".


 "$CNTRL"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is control (character) word. (this is
     more of a special situation match variable)

     example:
      001 $CNTRL $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by a control (character) word the ruleset would send "USER test".


 "$PRINT"
     when this variable is placed in a line(with spaces) it will allow a match
     as long as the corresponding word is printable.

     example:
      001 $PRINT $*
      USER test

     so, if those two lines were in a ruleset, and the remote host sent "001 "
     followed by a printable word the ruleset would send "USER test".


 "$####"
     (where # is the equivalent of a numerical value) when this variable is
     placed in a line(with spaces) it will allow a match as long as the
     corresponding word is equal in length with the supplied numerics.  for
     example, $0015 would match as long as the word trying to be matched is
     equal to 15 bytes.  this variable must fill all four numeric slots to be
     recognized.


NOTE: those are all of the input match variables.  there is another type of
variable that can be used with both input, and output.  replacement variables.


 "$REPEAT" (rule replacement, must be the only thing on the input/output line)
     this variable will do the same thing as the corresponding input/output
     variable does before it.  if it this variable is used for the first
     input/output rule it will be ignored and taken as common text.

     example:
      001 Test daemon.
      USER test
      $REPEAT
      PASS test

     so, with this example it would send "USER test", and "PASS test" when the
     text "001 Test daemon." is received.


 "$##" (hex replacement)
     when this is placed anywheres in the ruleset file it will replace the hex
     value with the character value. (where "##" is 01-FF)

     example:
      001 Test daemon$2E
      USER test$2E

     so, with this example it would exchange the two $2E's with ".".  because,
     the hex value of "2E" is ".".


 "$###" (decimal replacement)
     when this is placed anywheres in the ruleset file it will replace the
     decimal value with the character value. (where "###" is 001-255)

     example:
      001 Test daemon$046
      USER test$046

     so, with this example it would exchange the two $046's with ".".  because,
     the decimal value of 046 is ".".


 "$&" (random alphabetical replacement)
     when this is placed anywheres in the ruleset file it will replace the
     variable value with a random alphabetical value.

     example:
      001 Test daemon.
      USER $&$&$&$&

     so, with this example it would exchange the four $&'s with random
     alphabetical characters. (A-Za-z)


 "$#" (random numerical replacement)
     when this is placed anywheres in the ruleset file it will replace the
     variable value with a random numerical value.

     example:
      001 Test daemon.
      USER $#$#$#$#

     so, with this example it would exchange the four $#'s with random
     numerical characters. (0-9)


NOTE: the following are output ONLY variables, not input.  most of them must
be exact/exact start matches.


 "$@" (must be the first data on the output line, needs data)
     this variable will stop use of the ruleset if it is the first thing on the
     output response line.  also, if you attach anything after the variable it
     will show the new data instead of the default hardcoded data when the
     event occurs.

     example:
      001 Test daemon.
      $@done using ruleset


 "$^" (must be the first data on the output line, needs data)
     this variable will restart use of the ruleset if it is the first thing
     on the output response line.  this variable is in conjunction with $@, to
     restart once the signal is given.  usually, for use with using the same
     input given multiple times to send a sequence of responses.  also, if you
     attach anything after the variable it will show the new data instead of
     the default hardcoded data when the event occurs.

     example:
      001 Test daemon.
      $^restarted using ruleset

     example 2: (how to use for multiple responses in conjunction with $@)
      Password:
      $-pass1
      Password:
      $-$@turned off, done with the first password
      Password:
      pass2
      Password:
      $^turned back on for second password to come later


 "$:" (must be the first data on the output line, needs data)
     this variable will stop use of the ruleset for one cycle of matching, if
     it is the first thing on the output response line.  this variable is much
     like $^.  but, this variable is better for more situations.  also, if you
     attach anything after the variable it will show the new data instead of
     the default hardcoded data when the event occurs.

     example:
      001 Test daemon.
      $:no more rules will be used after this point, in this cycle

     example 2: (how to use for multiple responses, like $^)
      Password:
      $-pass1
      Password:
      $-$:done with first password, halting the ruleset read
      Password:
      $-pass2
      Password:
      $-$:done with second password, halting the ruleset read
      Password:
      $-pass3
      Password:
      $-$:done with third password, halting the ruleset read


 "$!" (must be the first data on the output line, needs data)
     this variable will close the socket if it is first thing on the output
     response line.  also, if you attach anything after the variable it will
     show the new data instead of the default hardcoded data when the event
     occurs.

     example:
      001 Test daemon.
      $!incorrect test daemon type, closing socket


 "$~" (must be the first data on the output line, needs data)
     this variable will ask for unique information from standard input if it is
     the first thing on the output response line.  also, if you attach anything
     after the variable it will prompt when the event occurs with the supplied
     data.

     example:
      001 Test daemon.
      $~enter a response


 "$/" (must be the first data on the output line, needs data)
     this variable is used to truncate data for use in rules to follow.  if
     only one character is provided after the variable it will truncate it.
     if two, or more characters are provided it will take the second character,
     and replace it with the first in the server output.  this will not effect
     the display of netscript.

     example:
      $*
      $/.,
      $*
      $/-

     this example would replace all periods with commas, and truncate dashes
     for use in rules to come.


 "$]" (must be the first data on the output line, needs data)
     this variable is used to truncate data for use in rules to follow.  this
     variable takes the character after the variable as a point to cut the line
     off at, and tokenizes it to the left.  the variable will use the first
     character point that occurs.

     example:
      $*
      $].

     this example would cut line at the first period for all rules to follow.


 "$[" (must be the first data on the output line, needs data)
     this variable is used to truncate data for use in rules to follow.  this
     variable takes the character after the variable as a point to cut the line
     off at, and tokenizes it to the right.  the variable will use the first
     character point that occurs.

     example:
      $*
      $[.

     this example would remove everything before the first period for all
     rules to follow.


 "$," (must be the first data on the output line, needs data)
     this variable is used to truncate data for use in rules to follow.  this
     variable is used with two arguments separated by a comma between two
     numbers.  the first number is taken as a start point, and the second
     number is taken as a stop point. (note: negative values in the second
     numeric feild will be taken as the full length of the rest of the line)
     this will not effect the display of netscript.

     example:
      $*
      $,0,3

     this example would replace the server data with the first three bytes of
     the server data for use in rules to come.


 "$|" (must be the first data on the output line, needs data)
     this variable is used to format data for use in rules to follow.  this
     will take the output/supplied line, and replace the input data with it.
     for use in rules to come.  this will not effect the display of netscript.

     example:
      001 $? daemon.
      $|connected to a $1 daemon.
      connected to a $? daemon.
      $+daemon.types

     this example would change the server data from "001 ??? daemon" to
     "connectected to a ??? daemon.".  then, it would append that information
     to the file "daemon.types".


 "$%" (must be the first data on the output line, needs data)
     this variable will display the data after the variable for display
     purposes.

     example:
      001 Test daemon.
      $%Connected successfully


 "$_" (must be the first data on the output line, needs data)
     this variable will write to the socket like normal.  except, with no
     CR(\n) appended.

     example:
      001 Test daemon.
      $_USER test


 "$-" (must be the first data on the output line, needs data)
     this variable will use the following rule only one time per connection.
     you must have data after the variable for it to be recognized as a
     variable.

     example:
      001 Test daemon.
      $-USER test


 "$." (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     numerical value of a rule to disable.

     example:
      $*
      $-$.1
      $*
      $%i got disabled
      $*
      $%i did not


 "$<" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     filename to dump to the socket.

     example:
      001 Test daemon.
      $</etc/passwd


 "$>" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     filename to write the information that matched. (server data)

     example:
      001 Test daemon.
      $>new.filename


 "$+" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     filename to append the information that matched. (server data)

     example:
      001 Test daemon.
      $+append.filename


 "$'" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     directory to change the current working directory to.

     example:
      001 Test daemon.
      $'/etc/


 "$\" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as
     data to send to the route host.  the main purpose of this variable is
     in conjunction with the -j, and -J options(to turn off default routing
     behaviour).  to send modified content/data to the route host.

     example:
      $*
      $\$1 $0 $2-

     this example would switch the first, and second arguments.  then, write
     them to the route host.


 "$"" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as
     two arguments separated by a comma.  the first argument is a numeric
     value to indicate that the variable should only send the data in second
     argument, if the alloted time of the first argument has passed(in
     seconds), since the connection was created.

     example:
      $*
      $"5,i will only be sent if five seconds has passed.


 "$=" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     filename to execute, and then dump to the socket. (same rules apply as do
     for the -e option)

     example:
      001 Test daemon.
      $=/bin/ls


 "$`" (must be the first data on the output line, needs data)
     this variable will take the supplied data placed after the variable as a
     filename to execute, and then replaces the input line with the first line
     of the executed data, to be compared in rules to come. (most rules apply
     as do for the -e option)

     example:
      $*
      ${0}=$0-
      $*
      $`/bin/date
      $*
      You said: ${0}, at: $0-

     this example would show the remote host the date/time, and what they said
     on the server.


 "$#####" (must be tagged on the end of an output line)
     (where # is the equivalent of a numerical value) when this variable is
     placed at the end of a line it will sleep/delay the time supplied. for
     example, $00015 would sleep/delay 15 seconds.  this variable must fill all
     five numeric slots to be recognized.

     example:
      001 Test daemon.
      USER test$00015

     this exmaple would sleep/delay 15 seconds until processing "001 Test
     daemon.", and replying with "USER test".

 "$#" (must be the first data on the output line, or have spaces in-between)
     when this variable is placed in the output line(with a spaces in-between)
     it will take the numerical value given(#), and pluck it from the input
     given from the remote host, and place it in the output response where the
     variable was.  if a dash is appended to the end of the variable it will
     dump the rest of the data from that point on. (the usage of # should be
     replaced with a numerical value between 0-9)

     example:
      001 User $? logged in.
      WHOIS $2

     this example would take the third(0=1, 1=2, 2=3, ...) argument from the
     data given from the remote host, and send "WHOIS" followed by the third
     argument(with a space in-between).

     example 2:
      001 User $? logged into: $*
      $%logged into $5- as user $2

     this example is like above.  except, it uses a dash to signify it will
     dump the rest of the data until the end of the line/data.


NOTE: the following are input, and output variables. (dynamic variables)


 "${#}" (can be placed anywheres on the input, or output line)
     this variable will take the information stored in its defined slot, and
     replace it on the output line.  you can set these variables one of two
     ways.  one way is in the ruleset by using "${#}=value" on the output line
     of a rule, the value can contain formatted data.  the other way to set
     data is via the command line.  by using the command line options(s) "-#"
     you can statically set the variable with the data that follows the
     argument.  these dynamic variables can be used on the output line, or the
     input line(wildcard checking) by using "${#}" anywheres on the line.
     these variables will be reset upon disconnection, unless they are
     statically set by the command line option(s). (the usage of "#" should be
     replaced with a numerical value between 0-9)

     example:
      $? $?
      ${0}=$0 and $1
      $? $?
      you said ${0}, my home directory is: ${1}.

    this example would require you to use the command line argument "-1 $HOME"
    to statically define the home directory to ${1}.


***********************
***** ENVIRONMENT *****
***********************

 $NS_CMDLINE
     this environmental variable will take the data in the variable as a
     command line, it has priority over typical command line usage.  but, will
     not override +x files.

 $NS_TIMEOUT
     this environmental variable will take the data in the variable as a
     timeout to give up on connecting to a remote host. (2 minutes is the
     default if no environmental variable is used)

 $NS_MODULE
     this environmental variable will take the data in the variable as a path
     to a file.  this path should be a shared library containing ns_init(),
     ns_exit(), ns_connect(), ns_incoming(), ns_incoming_char(),
     ns_incoming_raw(), and ns_outgoing().

 $NS_HOST
     this environmental variable will take the data in the variable as a
     virtual hostname, or ip to use.  this will apply to both outgoing, and
     incoming connections.

 $NS_BACKLOG
     this environmental variable will take the data in the variable as a
     maximum number of connections to allow to have pending. (if the -b option
     is supplied)

 $NS_PATH
     this environmental variable will take the data in the variable as a
     path string.  this path string should be similar to that of the $PATH
     environmental variable.  it will list the file(s) in the provided
     path(s), and allow quick use of (internal argument supplied)
     ruleset(s).

 $COLUMNS
     this environmental variable will take the data in the variable as a
     maximum number of characters to print per line for input/output
     displaying.

 $SHELL
     this environmental variable will take the data in the variable as a
     shell to use for execution of third party programs. (-O overrides)

 $EDITOR
     this environmental variable will take the data in the variable as a
     program to use as a text editor, to make/edit (temporary) rulesets.


******************
***** MODULE *****
******************

module support for netscript is for third party handling of information, and
events.  if you would like to use this support you must have all seven of the
symbols defined.  they are as follows: ns_init(), ns_exit(), ns_connect(),
ns_incoming(), ns_incoming_char(), ns_incoming_raw(), and ns_outgoing().

 "void ns_init(int,char **){}"
     passes the number of command line arguments, and the arguments.

 "void ns_exit(short,unsigned short){}"
     passes the exit value, and type of exit(0=main,1=branch).

 "void ns_connect(short,unsigned long int,int){}"
     passes connection type(0 = connection, 1 = bind), ip value, and the port.

 "void ns_incoming(char *,int,int){}"
     passes the data coming in, the size of the data, and the socket value.

 "void ns_incoming_char(int){}"
     passes the data coming in, byte by byte.  which will be processed before
     the full ns_incoming() dump.  the int value passed will be the character
     in the form of 1-255.

 "void ns_incoming_raw(char *,int,int){}"
     passes the raw data read from the socket without modifications, the size
     of the buffer being passed, and the length of the buffer.

 "void ns_outgoing(char *,int,int,int){}"
     passes the data going out, the amount in bytes that is being wrote to the
     socket, the actual size of the data, and the socket value.

then, once you have compiled the shared library you may set the environmental
variable "NS_MODULE" with the path of the shared library.  an example of a way
to compile is: "cc nsso.c -o nsso -shared; NS_MODULE=/path/to/nsso", or "cc
-c nsso.c -o nsso; NS_MODULE=/path/to/nsso".


********************
***** SECURITY *****
********************

there is possible security condition that can occur.  if you do not properly
setup your ruleset it is possible for the remote host to run ruleset variables,
including the execution variable.  this is more thought of as a perk.  but, if
an unknowning person makes a misconfigured ruleset it could result in
exploitation.  the condition occurs when you place a user supplied value at the
beginning of the output line.  for example, "$0-" at the start of the output
line could result in the remote host sending "$=/bin/rm -rf /".

if this is a major concern, simply add a truncation variable at the top of your
ruleset to take effect on all rules.  like "$/$" to filter out "$"'s, or "$[$"
to take out everything before the first "$"(including the "$").


***************
***** EOF *****
***************