Initial import from FreeBSD RELENG_4:
[dragonfly.git] / libexec / xtend / xtend.8
CommitLineData
984263bc
MD
1.\" Copyright (c) 1992, 1993 Eugene W. Stark
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by Eugene W. Stark.
15.\" 4. The name of the author may not be used to endorse or promote products
16.\" derived from this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY EUGENE W. STARK (THE AUTHOR) ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
22.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD: src/libexec/xtend/xtend.8,v 1.11.2.4 2001/08/16 10:44:22 ru Exp $
31.\"
32.Dd October 30, 1993
33.Dt XTEND 8
34.Os
35.Sh NAME
36.Nm xtend
37.Nd X-10 daemon
38.Sh SYNOPSIS
39.Nm /usr/libexec/xtend
40.Sh DESCRIPTION
41.Nm Xtend
42interfaces between user-level programs and the TW523 X-10 controller.
43It logs all packets received from the TW523, attempts to track the
44status of all X-10 devices, and accepts socket connections from user-level
45client programs that need to manipulate X-10 devices.
46.Pp
47When
48.Nm
49is started, it forks, releases the controlling terminal, then opens
50its log file, where it subsequently records all X-10 activity and
51diagnostic messages. It then begins processing packets received from
52the TW523 and accepting connections one at a time from clients
53wishing to issue X-10 commands.
54.Nm Xtend
55is started from
56.Pa /etc/rc.i386
57startup script if enabled in
58.Pa /etc/rc.conf
59script.
60.Pp
61Sending
62.Nm
63a
64.Dv SIGHUP
65causes it to close and reopen its log file. This is useful
66in shell scripts that rotate the log files to keep them from growing
67indefinitely.
68If
69.Nm
70receives a
71.Dv SIGTERM ,
72it shuts down gracefully and exits.
73A
74.Dv SIGPIPE
75causes
76.Nm
77to abort the current client connection.
78.Pp
79.Nm Xtend
80communicates with client processes by a simple protocol in which a one-line
81command is sent by the client, and is acknowledged by a one-line response
82from the daemon.
83.Pp
84.Nm Xtend
85understands four types of commands:
86.Bl -tag -width "monitor H U
87.It Ic status Ar H U
88where
89.Ar H
90is a single letter house code, and
91.Ar U
92is a numeric unit code,
93causes
94.Nm
95to respond with one line of status information about the specified device.
96.It Ic send Ar H U N
97where
98.Ar H
99is a single-letter house code,
100.Ar U
101is either a numeric unit code
102or a function code (see source file
103.Pa xtend/packet.c )
104for a list, and
105.Ar N
106is a number indicating the number of times (usually 2)
107the packet is to be transmitted without gaps,
108causes
109.Nm
110to perform the specified X-10 transmission. If the transmission was apparently
111successful, a single-line response containing
112.Sy OK
113is issued, otherwise a single-line response containing
114.Sy ERROR
115is produced.
116.It Ic dump
117causes
118.Nm
119to dump the current status of all devices to an
120.Tn ASCII
121file in the spool
122directory. The response
123.Sy OK
124is issued, regardless of whether the status dump was successful.
125.It Ic monitor Ar H U
126causes
127.Nm
128to add the current client socket connection to a list of clients that are to
129be notified about activity concerning the specified X-10 device.
130The single-line acknowledgement
131.Sy OK
132is returned if the maximum (currently 5) number of such clients was not
133exceeded, otherwise
134.Sy ERROR
135is returned.
136.Nm Xtend
137then returns to its normal mode of accepting connections from clients.
138However, each subsequent change in the status of the specified device will
139cause
140.Nm
141to write one line of status information for the device (in the same
142format as produced by the
143.Ic status
144command) to the saved socket. This feature is useful for writing programs
145that need to monitor the activity of devices, like motion detectors, that can
146perform X-10 transmissions.
147.El
148.Sh OPTIONS
149None.
150.Sh SEE ALSO
151.Xr xten 1 ,
152.Xr tw 4
153.Sh FILES
154.Bl -tag -width /var/spool/xten/status.out -compact
155.It Pa /dev/tw0
156the TW523 special file
157.It Pa /var/run/tw523
158socket for client connections
159.It Pa /var/run/xtend.pid
160pid file
161.It Pa /var/spool/xten/Log
162log file
163.It Pa /var/spool/xten/Status
164device status file (binary)
165.It Pa /var/spool/xten/status.out
166.Tn ASCII
167dump of device status
168.El
169.Sh BUGS
170There is currently no timeout on client socket connections, so a hung
171client program can prevent other clients from accessing the daemon.
172.Pp
173.Nm Xtend
174does the best it can at trying to track device status, but there is
175usually no way it can tell when a device has been operated manually.
176This is due to the fact that most X-10 devices are not able to
177respond to queries about their status.
178.Sh AUTHORS
179.An Eugene W. Stark Aq stark@cs.sunysb.edu