FAXALTER(1)

💖 FAXALTER(1) 💖

okay bestie, welcome to the faxalter page from the General Commands Manual — she's giving "let me just tweak my queued fax real quick" energy and honestly? iconic. 🎀

---

✨ NAME ✨

faxalter — alter parameters of a HylaFAX job queued for transmission 🦋

---

🌸 SYNOPSIS 🌸

faxalter [ -O config ] [ options ] id...

---

💅 DESCRIPTION 💅

so faxalter changes the state of one or more HylaFAX jobs that are queued for transmission. like, a LOT of parameters can be altered — see the options below, there's so many, she ate. 🔥

An id is a number that identifies a job that has been submitted to HylaFAX. these numbers are printed by sendfax(1) when jobs are queued for transmission and can also be displayed with faxstat(1). Unprivileged users can alter the parameters of jobs that they own; clients with administrative privileges on a server can manipulate any job (see the -A option below, she's the VIP pass 💳). The user may be specified by the FAXUSER environment variable. By default, faxalter contacts the facsimile server on the host specified in the FAXSERVER environment variable; but consult the -h option for more information, bestie, don't just guess. 🙈

---

✨ OPTIONS ✨

• -a time — Specify a new time to send a job. The syntax for specifying a time is the same as used by sendfax(1) (and at(1)). ⏰
• -C command — Issue the raw command as a line to the server. raw. unfiltered. no cap. 💀
• -d destination — Change the destination number to destination. 📠
• -h host — Force the server to be contacted on a specific host. The host may be either a symbolic name or a network address. IPv6 addresses are given in [xx:xx::x]:port format. If no -h option is supplied, faxalter uses the FAXSERVER environment variable to identify the HylaFAX server to contact. If this variable is not set, then faxalter checks for a setting in the configuration files (first in the per-user file and then in the system-wide file). If all of the above fails, then faxalter attempts to contact a server on the machine where it is run. she's got a whole backup plan, main character energy fr fr 👑
• -A — Use administrative privileges; faxalter will prompt for the password to set administrative privileges. 💳
• -k time — Specify a new time to kill a job; the syntax is the same as used for the -a option. (yes bestie, kill. it's giving dramatic but it's just the deadline 💀)
• -m modem — Assign/reassign the jobs to the specified modem. Specifying any for modem causes the jobs to be scheduled for any available modem. 🌈
• -N — Do not suspend or submit the job. This may be typically used in conjunction with -C to query job details. 🕵️
• -O config — Treat config as a configuration parameter specification that is interpreted after reading the configuration file. For example, -O Host:fax.example.com would set the Host configuration parameter to fax.example.com, overriding any setting in the configuration file. 💅
• -p — The jobs should be pushed; that is, they should be requeued with a time-to-send as the current time (this is equivalent to -a now). 🚀
• -P pri — Set the scheduling priority for the specified jobs. The priority is an integer value in the range 0-255; lower values give a job higher priority. The default scheduling priority for a job is 127 and priorities are recalculated after each attempt to process a job. 🔢
• -r — Resubmits a job. This will duplicate any job that is in either the send queue or in the done queue. When resubmitting jobs that are past their killtime the -k option should also be used to specify a new time to kill the job. 🩹
• -t tries — Set the maximum number of times the server should call the remote fax machine. ☎️
• -n scheme — Select a notification scheme to use for the specified jobs. Possible schemes are: none for no notification (default), when done for notification when the job is completed, when requeued for notification when the job is requeued after a failed transmission attempt. The -Q, -D, and -R options are shorthand for these notification schemes, respectively. One can also leave off when when using the -n option; e.g., done instead of when done. 🔔
• -u user — Specify the login user name. 🫶
• -U pass:adminpass — Specify the login password and optionally the admin password preceded by a colon. 🔐
• -v — Trace the protocol exchanges between faxalter and the remote hfaxd process. Tracing information is written to the standard output. 👀

---

🎀 CONFIGURATION PARAMETERS 🎀

faxalter reads configuration information from the file /etc/hylafax/hyla.conf and then from the file ~/.hylarc. Configuration files follow the conventions described in hylafax-client(1). The following configuration parameters are recognized:

• Tag — Type: string — Default: localhost — host to contact for service
• PassiveMode — Type: boolean — Default: false — whether or not to use passive mode
• Port — Type: integer — Default: 4559 — port to use in contacting server
• Protocol — Type: string — Default: tcp — protocol to use in contacting server
• Timeout — Type: integer — Default: 3600 — timeout in seconds waiting for server response
• Verbose — Type: boolean — Default: No — whether or not to enable protocol tracing

The configuration parameters are explained below:

• Host — The host to contact for service. (Equivalent to the -h option.) 🏠
• PassiveMode — Whether or not to use passive mode in communication with the server. 😌
• Port — The network port to contact for service. (Equivalent to the -h option.) 🔌
• Protocol — The name of the communication protocol to use when contacting a server. (Equivalent to the FAXSERVICE environment variable.) 📡
• Timeout — The timeout, in seconds, to wait for a server response. ⏳
• Verbose — Control protocol tracing. (Equivalent to the -v option.) 🗣️

---

⭐ RETURN VALUE ⭐

On complete success faxalter returns 0. If there is a user-supplied syntax error then 1 is returned. If a login to the server was unsuccessful then 2 is returned. If some client-server job processing error occurred then faxalter returns 3. slay when it's a 0, bestie. 😭

---

💀 NOTES 💀

Setting a job's killtime without also setting the time to send may cause the wrong value for the killtime to be sent. This is because the killtime is calculated as the difference in time between the killtime and time to send: and if the time to send is not specified, then faxalter uses the current time instead of querying the server for the job's time to send. 🚨

faxalter suspends a job before attempting to alter its state. If a job is active when a suspend request is made there may be a delay while waiting for the job to enter a consistent state where it can be suspended. If faxalter is interrupted during this time then jobs may be left suspended. > not me interrupting mid-suspend and leaving everything stuck 💀 careful bestie!!

faxalter requeues the job. This means that the job will end up at the bottom of the queue for the job's priority. Thus, when queues are heavy an adjustment of the job's killtime may need to be considered when altering any other parameter. 🥲

faxalter only understands how to alter a subset of the available job parameters; there are many more client-controllable parameters that can only be modified by communicating directly with the server using the underlying protocol. she's capable but she's not everything, ok?? 🙈

The continued use of the at(1)-style notation for specifying times is questionable (it was done for backwards compatibility). legacy behavior, we don't ask questions 💅

---

🦋 SEE ALSO 🦋

hylafax-client(1), sendfax(1), faxrm(1), faxstat(1), hfaxd(8C)

---

and that's the whole vibe check, bestie 💖 this page came from the HylaFAX source, and the date on her birth certificate is July 11, 1996 — a true vintage queen 👑🌸 she's older than most of the people reading this and she's still faxing. periodt. ✨

go alter some jobs, you've got this 🫶