1FAXSTAT(1)                  General Commands Manual                 FAXSTAT(1)
2
3
4

NAME

6       faxstat - display HylaFAX status
7

SYNOPSIS

9       faxstat [ -O config ] [ options ]
10

DESCRIPTION

12       faxstat  reports the status of HylaFAX servers, including (potentially)
13       the status of the send, receive, done, document, and  archive  directo‐
14       ries.   When invoked without options faxstat reports only the status of
15       the server; the options described below can be used  to  override  this
16       behavior.
17
18       Server  status  information  indicates  the  state of the server (idle,
19       sending, receiving, etc.)  and the phone number that is associated with
20       the fax modem.
21
22       The  job  queue  report  give  the  status of facsimile jobs queued for
23       transmission; by default:
24
25       ·  the job identifier,
26
27       ·  the job state (see below for the description of the a format in  the
28          JobFmt string),
29
30       ·  the modem or modem class the job is bound to (``any'' if the job can
31          be sent though any modem),
32
33       ·  the destination (phone number) of the job,
34
35       ·  the time to send the job, or a blank field if the job is being  pro‐
36          cessed or is to be sent immediately,
37
38       ·  the job's owner,
39
40       ·  and  status  information  about  the job (typically the reason why a
41          previous attempt failed).
42
43       The receive queue report lists the facsimile documents that  have  been
44       received and are awaiting delivery; by default it includes:
45
46       ·  the document protection mode,
47
48       ·  the number of pages,
49
50       ·  the document's owner,
51
52       ·  the phone number of the sender (if supplied),
53
54       ·  the date and time at which the job was received, and
55
56       ·  the  filename  of  the document in the recvq directory on the server
57          machine.
58

OPTIONS

60       -A        Login with administrative privileges.
61
62       -a        Display the contents of the archive directory on  the  server
63                 machine
64
65       -d        Display  the  status  of  all  jobs that have completed; i.e.
66                 those jobs located in  the  doneq  directory  on  the  server
67                 machine.  The JobFmt string defines the content and format of
68                 information reported with this option.
69
70       -f        Display the status of document  files  located  in  the  docq
71                 directory  on the server machine.  The FileFmt string defines
72                 the content and format  of  information  reported  with  this
73                 option (see below).
74
75       -g        Display  times  and  dates in Greenwich Mean Time (GMT).  NB:
76                 this is the default.
77
78       -h host   Report the status of the server on a specific host.  The host
79                 may  be  either  a  symbolic name or a network address.  IPv6
80                 addresses are given in ``[xx:xx::x]:port'' format.  If no  -h
81                 option  is  supplied,  faxstat uses the FAXSERVER environment
82                 variable to identify the HylaFAX server to contact.  If  this
83                 variable is not set, then faxstat checks for a setting in the
84                 configuration files (first in the per-user file and  then  in
85                 the system-wide file).  If all of the above fails, then faxs‐
86                 tat attempts to contact a server on the machine where  it  is
87                 run.
88
89       -i        Display additional status information for the server as given
90                 by /var/spool/hylafax/status/any.info.  This status typically
91                 has  information  such  as  the HylaFAX version, the physical
92                 location of the server machine, and an administrative contact
93                 for the server.  See status(5F).
94
95       -l        Display times and dates in the local timezone of the server.
96
97       -n        Supress the display of server and modem status.
98
99       -o login  Specify the fax owner login name.  If unspecified, the user's
100                 current login name is used.  The  login  password  and  admin
101                 password  may  also  be  provided by separating them from the
102                 owner login name with colons, like ``owner:pass:adminpass''.
103
104       -q        Display the sequence numbers of the HylaFAX queues.
105
106       -r        Display the receive queue status for each server.  The RcvFmt
107                 string defines the content and format of information reported
108                 with this option (see below).
109
110       -O config Treat config as a configuration parameter specification  that
111                 is  interpreted  after  reading  the configuration file.  For
112                 example, ``-O Host:fax.example.com'' would set the Host  con‐
113                 figuration  parameter  to ``fax.example.com'', overriding any
114                 setting in the configuration file.
115
116       -s        Display the status of jobs in the send queue  on  the  server
117                 machine.  The JobFmt string defines the content and format of
118                 information reported with this option (see below).
119
120       -v        Trace the protocol exchanges between faxstat  and  the  hfaxd
121                 processes on the standard output.
122

CONFIGURATION PARAMETERS

124       faxstat    reads    configuration    information    from    the    file
125       /etc/hylafax/hyla.conf and then from the file ~/.hylarc.  Configuration
126       files  follow the conventions described in hylafax-client(1).  The fol‐
127       lowing configuration parameters are recognized:
128       Tag              Type       Default      Description
129       FileFmt          string     see below    format string for file status results
130       Host             string     localhost    host to contact for service
131       JobFmt           string     see below    format string for job status results
132       ModemFmt         string     see below    format string for modem status results
133       PassiveMode      boolean    false        whether or not to use passive mode
134       Port             integer    4559         port to use in contacting server
135       Protocol         string     tcp          protocol to use in contacting server
136       RcvFmt           string     see below    format string for received facsimile status results
137       Timeout          integer    3600         timeout in seconds waiting for server response
138       TimeZone         string     GMT          timezone to use for reporting dates and times
139       Verbose          boolean    No           whether or not to enable protocol tracing
140
141       The configuration parameters are explained below:
142
143       FileFmt       The format string  to  use  when  returning  file  status
144                     information  with  the  -f option.  Formats are specified
145                     using printf(3S)-style conventions but  using  the  field
146                     identifiers  listed  below.   Each item can include field
147                     width,  precision,  left-justification,  0-filling,  etc.
148                     just  as  for  printf; e.g. %-8p for an 8-character wide,
149                     left-justified, blank-padded field  containing  the  file
150                     protection flags.
151
152                     Format    Description
153                     a         Last access time
154                     c         Creation time
155                     d         Device number (octal)
156                     f         Filename
157                     g         Group identifier (decimal)
158                     i         Inode number (decimal)
159                     l         Link count (decimal)
160                     m         Last modification time
161                     o         Owner (based on file GID)
162                     p         Fax-style protection flags (no group bits)
163                     q         UNIX-style protection flags
164                     r         Root device number (octal)
165                     s         File size in bytes (decimal)
166                     u         User identifier (decimal)
167
168       Host          The  host  to contact for service.  (Equivalent to the -h
169                     option.)
170
171       JobFmt        The format string to use when returning job status infor‐
172                     mation  for the -s and -d options.  Formats are specified
173                     using printf(3S)-style conventions but  using  the  field
174                     identifiers  listed  below.   Each item can include field
175                     width,  precision,  left-justification,  0-filling,  etc.
176                     just  as  for  printf;  e.g. %-3j for a 3-character wide,
177                     left-justified, blank-padded  field  containing  the  job
178                     state.
179
180                     Format    Description
181                     A         Destination SubAddress
182                     B         Destination Password
183                     C         Destination company name
184                     D         Total # dials/maximum # dials
185                     E         Desired signalling rate
186                     F         Client-specific tagline format string
187                     G         Desired min-scanline time
188                     H         Desired data format
189                     I         Client-specified scheduling priority
190                     J         Client-specified job tag string
191                     K         Desired use of ECM (one-character symbol)
192                     L         Destination geographic location
193                     M         Notification e-mail address
194                     N         Desired use of private tagline (one-character symbol)
195                     O         Whether to use continuation cover page (one-character symbol)
196                     P         # pages transmitted/total # pages to transmit
197                     Q         Client-specified minimum acceptable signalling rate
198                     R         Destination person (receiver)
199                     S         Sender's identity
200                     T         Total # tries/maximum # tries
201                     U         Page chopping threshold (inches)
202                     V         Job done operation
203                     W         Communication identifier
204                     X         Job type (one-character symbol)
205                     Y         Scheduled date and time
206                     Z         Scheduled time in seconds since the UNIX epoch
207                     a         Job state (one-character symbol)
208                     b         # consecutive failed tries
209                     c         Client machine name
210                     d         Total # dials
211                     e         Public (external) format of dialstring
212                     f         # consecutive failed dials
213                     g         Group identifier
214                     h         Page chop handling (one-character symbol)
215                     i         Current scheduling priority
216                     j         Job identifier
217                     k         Job kill time
218                     l         Page length in mm
219                     m         Assigned modem
220                     n         E-mail notification handling (one-character symbol)
221                     o         Job owner
222                     p         # pages transmitted
223                     q         Job retry time (MM::SS)
224                     r         Document resolution in lines/inch
225                     s         Job status information from last failure
226                     t         Total # tries attempted
227                     u         Maximum # tries
228                     v         Client-specified dialstring
229                     w         Page width in mm
230                     x         Maximum # dials
231                     y         Total # pages to transmit
232                     z         Time to send job
233
234                     The K format produces: ``D'' if ECM is to be disabled, ``
235                     '' (space) if ECM use is enabled, ``H'' if T.30  Annex  C
236                     half  duplex  is  enabled,  or ``F'' if T.30 Annex C full
237                     duplex is enabled.
238
239                     The N format produces: `` '' (space) if  the  system-wide
240                     tagline  format  is  to  be  used  or  ``P'' if a private
241                     tagline format is to be used.
242
243                     The O format produces: ``N''  if  no  continuation  cover
244                     page is to be used or `` '' (space) if the system default
245                     handling for continuation cover pages is to be used.
246
247                     The X format produces: ``F'' for a facsimile job or ``P''
248                     for a pager job.
249
250                     The  a  format  produces: ``?'' for a job in an undefined
251                     state, ``T'' for a suspended job (not  being  scheduled),
252                     ``P''  for a pending job (waiting for its time to send to
253                     arrive), ``S'' for a sleeping job (waiting for  a  sched‐
254                     uled  timeout  such as a delay between attempts to send),
255                     ``B'' for a job blocked by  concurrent  activity  to  the
256                     same  destination,  ``W'' for a job waiting for resources
257                     such as a free modem, ``R'' for a job  that  is  actively
258                     running,  and ``D'' for a job that is done and was a suc‐
259                     cess.  ``F'' for a job that failed to complete.
260
261                     The h format produces: ``D'' if  page  chopping  is  dis‐
262                     abled,  ``  ''  (space)  for the system default page chop
263                     handling, ``A'' when all pages  are  to  be  chopped,  or
264                     ``L'' if only the last page is to be chopped.
265
266                     The n format produces: `` '' (space) when no notification
267                     messages are to be delivered, ``D'' when notification  is
268                     to  be sent when the job is done, ``Q'' when notification
269                     is to be sent each time the job  is  requeued,  or  ``A''
270                     when  notification  is to be sent for either the job com‐
271                     pleting or being requeued.
272
273                     It is recommended that all items include a field width so
274                     that the width of column title strings can be constrained
275                     when constructing headers from the format string.
276
277       ModemFmt      The format string to  use  when  returning  modem  status
278                     information.      Formats     are     specified     using
279                     printf(3S)-style conventions but using the field  identi‐
280                     fiers  listed  below.  Each item can include field width,
281                     precision, left-justification, 0-filling,  etc.  just  as
282                     for  printf; e.g. %-8h for an 8-character wide, left-jus‐
283                     tified, blank-padded field containing  the  name  of  the
284                     host the server is running on.
285
286                     Format    Description
287                     h         Server hostname
288                     l         Local identifier string
289                     m         Canonical modem name
290                     n         FAX phone number
291                     r         Maximum pages that can be received in a single call
292                     s         Status information string
293                     t         Server and session tracing levels (xxxxx:yyyyy)
294                     v         Modem speaker volume as one-character symbol
295                     z         A ``*'' if a faxgetty(8C) process is running; otherwise `` '' (space)
296
297       PassiveMode
298                 Whether  or not to use passive mode in communication with the
299                 server.
300
301       Port          The network port to contact for service.  (Equivalent  to
302                     the -h option.)
303
304       Protocol      The  name  of the communication protocol to use when con‐
305                     tacting a server.  (Equivalent to the FAXSERVICE environ‐
306                     ment variable.)
307
308       RcvFmt        The  format  string to use when returning status informa‐
309                     tion for the -r  option.   Formats  are  specified  using
310                     printf(3S)-style  conventions but using the field identi‐
311                     fiers listed below.  Each item can include  field  width,
312                     precision,  left-justification,  0-filling,  etc. just as
313                     for printf; e.g. %-3b for a 3-character wide, left-justi‐
314                     fied, blank-padded field containing the signalling rate.
315
316                     Format    Description
317                     Y         Extended representation of the time when the receive happened
318                     a         SubAddress received from sender (if any)
319                     b         Signalling rate used during receive
320                     d         Data format used during receive
321                     e         Error description if an error occurred during receive
322                     f         Document filename (relative to the recvq directory)
323                     h         Time spent receiving document (HH:MM:SS)
324                     i         CIDName value for received fax
325                     j         CIDNumber value for received fax
326                     l         Page length in mm
327                     m         Fax-style protection mode string (``-rwxrwx'')
328                     n         File size (number of bytes)
329                     o         File owner
330                     p         Number of pages in document
331                     q         UNIX-style protection flags
332                     r         Resolution of received data
333                     s         Sender identity (TSI)
334                     t         Compact representation of the time when the receive happened
335                     w         Page width in mm
336                     z         A ``*'' if receive is going on; otherwise `` '' (space)
337
338                     It is recommended that all items include a field width so
339                     that the width of column title strings can be constrained
340                     when constructing headers from the format string.
341
342       TimeZone      Control whether times and dates are reported in the local
343                     timezone of the server (``local'') or in  GMT  (``gmt'').
344                     By default times are reported in GMT.
345
346       Timeout       The timeout, in seconds, to wait for a server response.
347
348       Verbose       Control protocol tracing.  (Equivalent to the -v option.)
349

NOTES

351       The  server login user name may be specified by the FAXUSER environment
352       variable.
353

BUGS

355       There is no way to suppress the server status report.  There is no  way
356       to control the printing of headers.
357

FILES

359       /etc/hylafax/hyla.conf    system-wide configuration file
360       ~/.hylarc                 per-user configuration file
361

SEE ALSO

363       hylafax-client(1), sendfax(1), faxalter(1), faxrm(1), hfaxd(8C)
364
365
366
367                                 July 9, 1996                       FAXSTAT(1)
Impressum