.\"    $Header: /home/ahuxley/dev/arc/ppplc/man/RCS/sndmsg.1.shpp,v 1.9 1999/04/28 11:03:37 alexis Exp $
.\"
#shpp include ../bin/sm_msgids.shpp
#shpp include ../bin/ppplc_msgids.shpp
.PP
.TH SNDMSG 1 "15 January 1999"
.SH NAME
Sndmsg \- PPP Link Control Message Sender
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH SYNOPSIS
.B sndmsg
[
.B \-v
|
.B \-d
.I level
] [
.B \-q
.I delay
] [
.B \-t 
.I recipient
]
.I msgid 
[
.I msgpars
] ...
.br
.B "sndmsg -V"
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH DESCRIPTION
This man page documents 
.I sndmsg
version MARKER_PATCHLEVEL.
.PP
.I Sndmsg
is a lightweight program to send messages to a message queue read by
.I ppplcd\fR(8). 
It is primarily for use in scripts, such as
.I ppplcc\fR(1),
.I qtest\fR(UNDOCUMENTED),
.I usecnt\fR(UNDOCUMENTED)
as well as in cron jobs (see 
.I cron\fR(8)),
user startup scripts.
.PP
Message ids are numeric. Certain message ids require a fixed number of
parameters. Currently only integer parameters are supported. Currently two
programs read the messages dispatched by 
.I sndmsg\fR:
.I ppplcd\fR(8)
and
.I getmsg\fR(UNDOCUMENTED). 
This page only documents messages useful to end-users.
There are many more internally used messages. For information on those, please
refer to the C sources.
.br
.ne 5
.SH OPTIONS
.\"  This indents everything after the next line by 25 somethings.
.TP 25
.B \-V
Print the version number and exit.
.TP
.B \-v
Sets the verbosity level to include errors, warnings and informational
mesaages.
.TP
.B \-d \fIlevel
Sets the verbosity level to 
.I level\fR.
Each binary bit in 
.I level
turns on a different debugging facility. This option is not intended for
end-users. The various bits and their meanings change regularly. For
more information see the proram C sources.
.TP
.B \-q \fIdelay
Instead of the message being acted upon immediately, the messages are
only queued immediately, but only processed after the specified delay
in seconds.
.TP
.B \-t \fIrecipient
By default messages are marked for the attention of 
.I ppplcd\fR(8)\fR,
but they may be marked for the attention of other programs which know how
to read the message queue. This feature is currently not for end-users.
.PD
.PP 
The following messages are currently supported. This list is very
dynamic, so upgrading this program may break any locally written 
scripts. Beware!
.TP 25
.B MARKER_MSGID_EXEC_PPPD
Call 
.I pppd\fR(8)
to connect.
.TP
.B MARKER_MSGID_SET_QUIT
Instruct 
.I ppplcd\fR(8)
to exit.
.TP
.B MARKER_MSGID_HANGUP
Kill any currently running
.I pppd\fR(8),
closing the connection if there is one.
If 
.I pppd\fR(8)
is in an uninterruptable state, then it will be killed at the 
earliest opportunity.
.TP
.B MARKER_MSGID_NOACTION
Do nothing.
.TP
.B MARKER_MSGID_SET_IDLEPARS \fIidletimeout
Set the idle timeout to the specified value in seconds. 0 indicates no
idle timeout, although beware that changing this value will not reset
any idle timeout set at the remote end of the connection, nor will it
regenerate the chatscript.
.TP
.B MARKER_MSGID_EXEC_ANNOUNCE \fIannouncementid
Instruct 
.I ppplcd\fR(8)
to call the announcement program (specified in its config file), with 
the parameter
.I announcementid\fR.
.TP
.B MARKER_MSGID_SET_QUALITY \fIminquality checkinterval
Sets the minimum acceptable quality to 
.I minquality
and the interval at which quality checks are made to
.I checkinterval\fR.
If as a result of sending this message, either argument is now zero, then
quality checking ceases. Similarly if both arguments are now non-zero, then
quality checking is initiated. Beware that depending on the script used to
perform quality checking, quality checking may constitute use of the link
and as such interfere with idle timeouts.
.TP
.B MARKER_MSGID_INFO_REQ \fIrecipient
Requests information about the value of many internal variables. The information
is marked for the attention of 
.I recipient\fR.
This information is intended to be read with 
.I getmsg\fR(UNDOCUMENTED),
which will sooner or later be used by both
.I ppplcc\fR(1) 
and 
.I xppplcc\fR(1).
.TP
.B MARKER_MSGID_SET_DONEWS
Enable post-connect-time news transfer.
.TP
.B MARKER_MSGID_EXEC_MISC
Perform miscellanous commands, as specified in config file.
.TP
.B MARKER_MSGID_UNSET_DONEWS
Disable post-connect-time news transfer.
.TP
.B MARKER_MSGID_SET_DEBUG \fIlevel
set debugging level to 
.I level\fR.
.TP 
.B MARKER_MSGID_SET_AUTORECONNECT
Enable autoreconnect. That is if the remote end hangs up, then the local
end will immediately attempt to reconnect.
.TP
.B MARKER_MSGID_UNSET_AUTORECONNECT
Disable autoreconnect. 
.TP
.B MARKER_MSGID_EXEC_MAIL
Perform mail transfer now.
.TP
.B MARKER_MSGID_EXEC_NEWS
Perform news transfer now.
.TP
.B MARKER_MSGID_DEL_MSGID \fImsgid
Delete any delayed messages of type 
.I msgid\fR.
.PD
.br
.ne 5
.SH EXAMPLES
.PP 
The following 
.I crontab\fR(1)
entries would instruct 
.I ppplcd\fR(8)
to call
.I pppd\fR(8)
to connect at 7.30 am each working day, and to disconnect 15 minutes later
if it hadn't already hung up:
.nf
.IP
30 7 * * 1-5 MARKER_LCLBINDIR/sndmsg MARKER_MSGID_EXEC_PPPD
45 7 * * 1-5 MARKER_LCLBINDIR/sndmsg MARKER_MSGID_HANGUP
.fi
.PP 
or alternatively:
.nf
.IP
30 7 * * 1-5 ( MARKER_LCLBINDIR/sndmsg MARKER_MSGID_EXEC_PPPD; MARKER_LCLBINDIR/sndmsg -q 900 MARKER_MSGID_HANGUP )
.fi
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONENT VARIABLES
None.
.br 
.ne 5
.SH DIAGNOSTICS
Only diagnostic messages which are so cryptic that they need to be explained
are explained here.
.PD 0
.TP 25
.B sndmsg: ERROR: can't queue message (\fIerrno\fB)
This message should not appear! Please report it if you see it.
.TP
.B sndmsg: INTERNAL ERROR: failed to locate msgid \fImsgid\fB in table
Internally required information pertaining to the specified message id could
not be located. Did you use a message id not documented on this page?
.PD 
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH SEE ALSO
ppplcc(1), ppplcd(8), pppd(8), cron(8), crontab(1)
.br
.ne 5
.SH AUTHOR
Alexis Huxley
.br
.ne 5
.SH BUGS
No known bugs.
.PP
Bug reports and queries should be reported to
.B ppplc-support@danae.demon.co.uk\fR.
.PP
For the latest release of
.I ppplc\fR,
visit
.B http://www.danae.demon.co.uk/software/ppplc/\fR.
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1996-1999 Alexis Huxley
.PP
This program 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.
.PP
This program 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.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.