Merge from vendor branch BINUTILS:
[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 $
d600454b 31.\" $DragonFly: src/libexec/xtend/xtend.8,v 1.3 2006/02/17 19:33:32 swildner Exp $
984263bc
MD
32.\"
33.Dd October 30, 1993
34.Dt XTEND 8
35.Os
36.Sh NAME
37.Nm xtend
38.Nd X-10 daemon
39.Sh SYNOPSIS
40.Nm /usr/libexec/xtend
41.Sh DESCRIPTION
42.Nm Xtend
43interfaces between user-level programs and the TW523 X-10 controller.
44It logs all packets received from the TW523, attempts to track the
45status of all X-10 devices, and accepts socket connections from user-level
46client programs that need to manipulate X-10 devices.
47.Pp
48When
49.Nm
50is started, it forks, releases the controlling terminal, then opens
51its log file, where it subsequently records all X-10 activity and
52diagnostic messages. It then begins processing packets received from
53the TW523 and accepting connections one at a time from clients
54wishing to issue X-10 commands.
55.Nm Xtend
56is started from
57.Pa /etc/rc.i386
58startup script if enabled in
59.Pa /etc/rc.conf
60script.
61.Pp
62Sending
63.Nm
64a
65.Dv SIGHUP
66causes it to close and reopen its log file. This is useful
67in shell scripts that rotate the log files to keep them from growing
68indefinitely.
69If
70.Nm
71receives a
72.Dv SIGTERM ,
73it shuts down gracefully and exits.
74A
75.Dv SIGPIPE
76causes
77.Nm
78to abort the current client connection.
79.Pp
80.Nm Xtend
81communicates with client processes by a simple protocol in which a one-line
82command is sent by the client, and is acknowledged by a one-line response
83from the daemon.
84.Pp
85.Nm Xtend
86understands four types of commands:
87.Bl -tag -width "monitor H U
88.It Ic status Ar H U
89where
90.Ar H
91is a single letter house code, and
92.Ar U
93is a numeric unit code,
94causes
95.Nm
96to respond with one line of status information about the specified device.
97.It Ic send Ar H U N
98where
99.Ar H
100is a single-letter house code,
101.Ar U
102is either a numeric unit code
103or a function code (see source file
104.Pa xtend/packet.c )
105for a list, and
106.Ar N
107is a number indicating the number of times (usually 2)
108the packet is to be transmitted without gaps,
109causes
110.Nm
111to perform the specified X-10 transmission. If the transmission was apparently
112successful, a single-line response containing
113.Sy OK
114is issued, otherwise a single-line response containing
115.Sy ERROR
116is produced.
117.It Ic dump
118causes
119.Nm
120to dump the current status of all devices to an
121.Tn ASCII
122file in the spool
123directory. The response
124.Sy OK
125is issued, regardless of whether the status dump was successful.
126.It Ic monitor Ar H U
127causes
128.Nm
129to add the current client socket connection to a list of clients that are to
130be notified about activity concerning the specified X-10 device.
131The single-line acknowledgement
132.Sy OK
133is returned if the maximum (currently 5) number of such clients was not
134exceeded, otherwise
135.Sy ERROR
136is returned.
137.Nm Xtend
138then returns to its normal mode of accepting connections from clients.
139However, each subsequent change in the status of the specified device will
140cause
141.Nm
142to write one line of status information for the device (in the same
143format as produced by the
144.Ic status
145command) to the saved socket. This feature is useful for writing programs
146that need to monitor the activity of devices, like motion detectors, that can
147perform X-10 transmissions.
148.El
149.Sh OPTIONS
150None.
984263bc
MD
151.Sh FILES
152.Bl -tag -width /var/spool/xten/status.out -compact
153.It Pa /dev/tw0
154the TW523 special file
155.It Pa /var/run/tw523
156socket for client connections
157.It Pa /var/run/xtend.pid
158pid file
159.It Pa /var/spool/xten/Log
160log file
161.It Pa /var/spool/xten/Status
162device status file (binary)
163.It Pa /var/spool/xten/status.out
164.Tn ASCII
165dump of device status
166.El
d600454b
SW
167.Sh SEE ALSO
168.Xr xten 1 ,
169.Xr tw 4
170.Sh AUTHORS
171.An Eugene W. Stark Aq stark@cs.sunysb.edu
984263bc
MD
172.Sh BUGS
173There is currently no timeout on client socket connections, so a hung
174client program can prevent other clients from accessing the daemon.
175.Pp
176.Nm Xtend
177does the best it can at trying to track device status, but there is
178usually no way it can tell when a device has been operated manually.
179This is due to the fact that most X-10 devices are not able to
180respond to queries about their status.