diff options
Diffstat (limited to 'man1p/qmsg.1p')
| -rw-r--r-- | man1p/qmsg.1p | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/man1p/qmsg.1p b/man1p/qmsg.1p new file mode 100644 index 000000000..f0e6b2a48 --- /dev/null +++ b/man1p/qmsg.1p @@ -0,0 +1,214 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qmsg +.SH NAME +qmsg \- send message to batch jobs +.SH SYNOPSIS +.LP +\fBqmsg\fP \fB[\fP\fB-E\fP\fB][\fP\fB-O\fP\fB]\fP \fImessage_string +job_identifier\fP \fB... +\fP +.SH DESCRIPTION +.LP +To send a message to a batch job is to request that a server write +a message string into one or more output files of the batch +job. A message is sent to a batch job by a request to the batch server +that manages the batch job. The \fIqmsg\fP utility is a +user-accessible batch client that requests the sending of messages +to one or more batch jobs. +.LP +The \fIqmsg\fP utility shall write messages into the files of batch +jobs by sending a \fIJob Message Request\fP to the batch +server that manages the batch job. The \fIqmsg\fP utility shall not +directly write the message into the files of the batch +job. +.LP +The \fIqmsg\fP utility shall send a \fIJob Message Request\fP for +those batch jobs, and only those batch jobs, for which a +batch \fIjob_identifier\fP is presented to the utility. +.LP +The \fIqmsg\fP utility shall send \fIJob Message Request\fPs for batch +jobs in the order in which their batch +\fIjob_identifier\fPs are presented to the utility. +.LP +If the \fIqmsg\fP utility fails to process any batch \fIjob_identifier\fP +successfully, the utility shall proceed to process +the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqmsg\fP utility shall not exit before a \fIJob Message Request\fP +has been sent to the server that manages the batch +job that corresponds to each successfully processed batch \fIjob_identifier\fP. +.SH OPTIONS +.LP +The \fIqmsg\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-E\fP +Specify that the message is written to the standard error of each +batch job. +.LP +The \fIqmsg\fP utility shall write the message into the standard error +of the batch job. +.TP 7 +\fB-O\fP +Specify that the message is written to the standard output of each +batch job. +.LP +The \fIqmsg\fP utility shall write the message into the standard output +of the batch job. +.sp +.LP +If neither the \fB-O\fP nor the \fB-E\fP option is presented to the +\fIqmsg\fP utility, the utility shall write the message +into an implementation-defined file. The conformance document for +the implementation shall describe the name and location of the +implementation-defined file. If both the \fB-O\fP and the \fB-E\fP +options are presented to the \fIqmsg\fP utility, then the +utility shall write the messages to both standard output and standard +error. +.SH OPERANDS +.LP +The \fIqmsg\fP utility shall accept a minimum of two operands, \fImessage_string\fP +and one or more batch +\fIjob_identifier\fPs. +.LP +The \fImessage_string\fP operand shall be the string to be written +to one or more output files of the batch job followed by a +<newline>. If the string contains <blank>s, then the application shall +ensure that the string is quoted. The +\fImessage_string\fP shall be encoded in the portable character set +(see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character Set). +.LP +All remaining operands are batch \fIjob_identifier\fPs that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqmsg\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqmsg\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqmsg\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqmsg\fP utility allows users to write messages into the output +files of running jobs. Users, including operators and +administrators, have a number of occasions when they want to place +messages in the output files of a batch job. For example, if a +disk that is being used by a batch job is showing errors, the operator +might note this in the standard error stream of the batch +job. +.LP +The options of the \fIqmsg\fP utility provide users with the means +of placing the message in the output stream of their choice. +The default output stream for the message-if the user does not designate +an output stream-is implementation-defined, since many +implementations will provide, as an extension to this volume of IEEE\ Std\ 1003.1-2001, +a log file that shows the history +of utility execution. +.LP +If users wish to send a message to a set of jobs that meet a selection +criteria, the \fIqselect\fP utility can be used to acquire the appropriate +list of job identifiers. +.LP +The \fB-E\fP option allows users to place the message in the standard +error stream of the batch job. +.LP +The \fB-O\fP option allows users to place the message in the standard +output stream of the batch job. +.LP +Historically, the \fIqmsg\fP utility is an existing practice in the +offerings of one or more implementors of an NQS-derived +batch system. The utility has been found to be useful enough that +it deserves to be included in this volume of +IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqselect\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |