gold: Fix hardcoded library search path
[dragonfly.git] / share / man / man4 / man4.i386 / gsc.4
CommitLineData
984263bc
MD
1.\" gsc.4 - manual page for the scanner device driver `gsc'
2.\"
3.\"
4.\" Copyright (c) 1995 Gunther Schadow. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by Gunther Schadow.
17.\" 4. The name of the author may not be used to endorse or promote products
18.\" derived from this software without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30.\"
31.\" $FreeBSD: src/share/man/man4/man4.i386/gsc.4,v 1.12.2.7 2001/12/17 11:30:13 ru Exp $
32.\"
33.Dd January 9, 1995
984263bc 34.Dt GSC 4 i386
fb5b3747 35.Os
984263bc
MD
36.Sh NAME
37.Nm gsc
38.Nd a device driver for a handy scanner
39.Sh SYNOPSIS
40.In machine/gsc.h
41.Pp
42.Cd Minor number bits: Ar uu d g p ...
43.Bl -tag -width "uu " -compact -offset indent
44.It Ar uu
45unit gsc0 .. gsc3
46.It Ar d
47selects logging of
48.Em debug
49messages
50.It Ar g
51selects
52.Em bitmap
53vs.
54.Em graymap
55output
56.It Ar p
57selects
58.Em raw
59vs. portable
60.Em pnm
61output
62.El
63.Sh DESCRIPTION
64The
65.Nm
66character device driver currently handles only the
67Genius GS-4500 handy scanner.
68It operates in pure DMA modes, although
69the hardware could be set up to work with irq.
70I had neither enough
71documentation nor experience in writing interrupt driven device
72drivers.
73.Pp
74The device can operate at four different
75.Em resolutions :
76100, 200,
77300 and 400dpi.
78It produces a simple bitmap with the most significant
79bit at the left side.
80The driver can optionally output the famous and
81likely simple portable bitmap file format
82.Xr pbm 5
83by Jef Poskanzer.
84Thus the scans can easily processed by any graphic package around
3e9b6948 85.Xr ( xpaint 1 ,
984263bc
MD
86.Xr xv 1 ,
87.Xr xli 1
88only to name some of them ...). In
89.Em raw
90mode a
91bit which is set means a black pixel because the scanner detects black
92points on white paper.
93On the other hand, because pnm format describes
94intensities of electron beams in video screens a set bit in
95.Em pbm
96mode means a white pixel.
97.Pp
98The
99.Em width
100of the output bitmap is fixed as given by the
101resolution value.
102However, the
103.Em height
104of the bitmap must be
105supplied in
106.Em pnm
107mode since the driver must know at what time the
108.Sq end-of-file
109shall be reached.
110With this feature you are able to
111directly copy the scanner output into a pbm file with
3867d280 112.Xr cat 1 .
984263bc
MD
113Of course you can obtain a similar effect by using
114.Xr dd 1
115with the driver in
116.Em raw
117mode.
118.Pp
119The
120.Em graymap
121output mode is not yet implemented into the driver.
122It is even questionable if external programs would not do this job
123better thereby not counting to the size of the kernel.
124Even though, I
125do not know of tools which produce a graymap from a halftone bitmap.
126.Pp
127The ioctl requests that are served by
128.Nm
129are listed below.
130There is a utility, called
131.Xr sgsc 1 ,
132that provides access to these
133requests from within shell.
134.Bl -tag -width Ds
b1c94e87 135.It Dv GSC_SRES Vt int
984263bc
MD
136Set the
137.Em resolution
138value.
139If this call is made after the first
140read access to the device there will be no effect unless the device is
141closed and opened again.
b1c94e87 142.It Dv GSC_GRES Vt int
984263bc 143Get current resolution in dots per inch (dpi).
b1c94e87 144.It Dv GSC_SRESSW Vt void
984263bc
MD
145Set resolution value from selector switch.
146The driver must be in an
147open though untouched state otherwise the request will fail and
148.Xr errno 2
149is set to
150.Er EBUSY .
b1c94e87 151.It Dv GSC_SWIDTH Vt int
984263bc
MD
152Set the
153.Em width
154of the bitmap.
155Actually, this is an alternative
156way of setting the resolution, since any allowed resolution matches
157exactly one width.
158Allowed are listed in the table below.
159.Bl -tag -width resolution -compact -offset indent
160.It resolution
161width
162.It 100 dpi
163424 pixels
164.It 200 dpi
165840 pixels
166.It 300 dpi
1671264 pixels
168.It 400 dpi
1691648 pixels
170.It ?
1711696 pixels
172.It ?
1732544 pixels
174.It ?
1753648 pixels
176.El
177.Pp
178Values which are not reported in the above table will cause the ioctl
179call to fail with
180.Xr errno 2
181set to
182.Er EINVAL .
183.Pp
184As you can see, there are width values > 1696.
185This does, however, not
186mean that you can obtain scanned lines longer than the width of your
187scanner or by higher resolutions.
188Actually, the resolution is selected
189by only by the hardware switch.
190Any line that is longer than what is
191defined for the actual resolution will be undefined (usually white) on
192the right part that is exceeding the standard line.
b1c94e87 193.It Dv GSC_GWIDTH Vt int
984263bc 194Get current width of the bitmap in pixels.
b1c94e87 195.It Dv GSC_SHEIGHT Vt int
984263bc
MD
196Set the
197.Em height
198of the bitmap in
199.Em pnm
200mode.
201This is actually
202a limit on the amount of lines scannable after the first read
203operation.
204When the limit is reached read will return 0. However, the
205device is turned off only when a close is performed (either
206explicitly or implicitly on exit of the calling process).
b1c94e87 207.It Dv GSC_GHEIGHT Vt int
984263bc 208Get the current height of the bitmap.
b1c94e87 209.It Dv GSC_SBLEN Vt int
984263bc
MD
210Set the length of the buffer used internally to do the DMA transfer.
211The buffer length is supplied in lines of the bitmap.
212Since the buffer
213size limit is (currently) 0x3000 bytes the maximum number of lines
214allowed will vary with the width of each line.
215This upper limit is
3f5e28f4 216checked before it overwrites the current value and passes an
984263bc
MD
217.Er ENOMEM
218in the
219.Xr errno 2
220variable.
221However, since the bitmap width can change
222after a buffer length was selected a read request may fail with
223.Er ENOMEM
224if the buffer length turns out too high.
225It is generally wise to
226choose long buffers rather than go save in order to obtain better
227output.
b1c94e87 228.It Dv GSC_GBLEN Vt int
984263bc 229Get the current buffer length in lines.
b1c94e87 230.It Dv GSC_SBTIME Vt int
984263bc
MD
231Set the timeout for the completion of reading one buffer.
232Since a
233handy scanner is a human/computer interface timeout values are usually
234higher than those of a flat scanner.
235Default is 15 seconds.
236After
237timeout is reached the read operation will fail with
238.Er EBUSY .
239Note that
240the timeout timer starts anew for each buffer to be read and thus does
241not cause you to scan faster for longer images.
242BLEN/BTIME is similar
243as MIN/TIME in
244.Xr termios 4 .
b1c94e87 245.It Dv GSC_GBTIME Vt int
984263bc
MD
246Get the current buffer timeout.
247.El
248.Pp
b1c94e87
SW
249All ioctl requests that modify a parameter except
250.Dv GSC_SBTIME
251do not
984263bc
MD
252have an effect on an ongoing scan process, i.e. after the first read
253request that follows open.
254You must close the device and open it again
255for the new selections to take effect.
256Consequently, the selections
257are not reset when you close or open the device.
258.Pp
259Similarly, requests that read a value do not report the value that is
260used for the ongoing scan process.
261The values needed during the scan
262process are saved when it starts and thus are not accessed by ioctl
263requests.
264.Pp
265The BTIME value does, however, have an immediate effect on the ongoing
266scan.
267Thus the timeout can for example be set to long until the user
268starts scanning. It can then be set to a short amount to react
269(nearly) immediately when the user stops.
270Note that the user should be
271left time to at least fill one buffer without having to haste.
272.Pp
273Note that the
274.Em pbm
275versus
276.Em raw
277mode selection is done by the
278minor number not by ioctl requests.
279In
280.Em raw
281mode the selected
282height of the bitmap will have no effect.
283.Sh FILES
284.Bl -tag -width /dev/gsc0pd
285.It Pa /dev/gsc0
286device node for
287.Em raw
288output, has minor number 0.
289.It Pa /dev/gsc0d
290device node for
291.Em raw
292output emitting
293.Em debug
294messages if the
295GSCDEBUG option was given at compile time, has minor number 32.
296.It Pa /dev/gsc0p
297device node for output in
298.Em pbm
299file format, has minor number 8.
300.It Pa /dev/gsc0pd
301device node for
302.Em pbm
303and
304.Em debug
305mode, has minor number 40.
306.El
307.Sh EXAMPLES
308.Bd -literal -offset indent
309dd if=/dev/gsc0 of=rawfile bs=(width/8) count=(height)
310
311cat /dev/gsc0p > pbmfile
312.Ed
313.Sh DIAGNOSTICS
314.Bl -tag -width Cd
315.It GSCDEBUG
316When you define this name as an `option' in the kernel configuration
317you can get debug output if you access the driver with a minor number
318whose debug bit (i.e. bit 5 out of 7) is set.
319.El
320.Sh SEE ALSO
321.Xr cat 1 ,
322.Xr dd 1 ,
7cd7d057 323.Xr pbmtopgm 1 Pq Pa pkgsrc/graphics/netpbm ,
984263bc
MD
324.Xr sgsc 1 ,
325.Xr close 2 ,
326.Xr intro 2 ,
327.Xr ioctl 2 ,
328.Xr open 2 ,
329.Xr read 2 ,
330.Xr termios 4 ,
7cd7d057
SW
331.Xr pbm 5 Pq Pa pkgsrc/graphics/netpbm ,
332.Xr pnm 5 Pq Pa pkgsrc/graphics/netpbm
984263bc
MD
333.Sh AUTHORS
334.An Gunther Schadow Aq gusw@fub46.zedat.fu-berlin.de
335.Sh BUGS
336Even though the scanner device has a little switch by which you should
337be able to select one of the four resolution modes, I could not yet
338determine how to read its status.
339Unless this is not fixed the driver
340depends on the value passed by means of
341.Xr ioctl 2
342which need not match
343what is selected by the hardware.