Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

mh-format(5mh) [ultrix man page]

mh-format(5mh)															    mh-format(5mh)

       mh-format - format file for MH message system

       Several MH commands utilize either a string or a file during their execution.  For example, uses a format string which specifies how should
       generate the listing for each message; uses a format file which directs it how to generate the reply to a message, and so on.

       This reference page describes how to write new format commands or modify existing ones.	You should not attempt	this  unless  you  are	an
       experienced MH user.

       A format string is similar to a string, but uses multi-letter escapes.  The rest of this reference page assumes a knowledge of the routine.
       When specifying a string, the usual C backslash characters are honored: and Continuation lines in format files end  with  followed  by  the
       newline character.

       When  an escape is interpreted and the result is immediately printed, you can specify an optional field width to print the field in exactly
       a given number of characters.  A numeric escape, such as will print at most 4 digits of the value.  Any overflow is  marked  by	a  in  the
       first  position,  for example A string escape, such as will print the first four characters of the string.  In both cases, short fields are
       padded at the right, usually with a blank.  If the field width argument begins with a zero, for example the fill character is a zero.

       The interpretation model is based on a simple machine with two registers, and The former contains an integer value,  the  latter  a  string
       value.	When  an  escape  is processed, if it requires an argument, it reads the current value of either or and, if it returns a value, it
       writes either or

       Escapes are of three types: and

   Component Escapes
       A component escape represents a header field in the message being processed.  It is written where the name is the name of the header field.
       For example, refers to the field of the message.

       The  value of a component escape is the content of the named field.  This is always a string.  For example, the header of an unsent message
       might look as follows:
       To: smith@local
       cc: davis
       Subject: tomorrow's meeting
       In this example, the value of the component escape is the string

   Control Escapes
       A control escape is one of: and These correspond to if-then-else constructs.

       There are two syntaxes allowed by these control escapes.  The first is:
       If the function or component is non-zero (for integer-valued escapes) or non-empty (for string-valued escapes), everything up to the corre-
       sponding is interpreted.  Otherwise, skip to the next and begin interpreting again.

       The second form of syntax is as follows:
       If  the	function  or  component is non-zero or non-null, the is interpreted.  Otherwise, skip to and interpret the Only one string is ever
       interpreted; if the first string is interpreted, the system skips from the control escape to the character.

   Function Escapes
       A function escape is specified as and is statically defined.

       Most functions expect an argument of a particular type.	In the tables of functions that follow, these types are referred to:

       A literal number or string; for example,
		 takes the number 1234 as its argument.

       Any header component; for example,
		 takes the contents of the From: header field as an argument.

       An optional component, function or string, perhaps nested.
		 For example, takes the return value of the function as its argument.  If no argument is provided, the function will  read  either
		 the or the register, as appropriate.

       Functions return three types of values: and, for those functions which return a true or false status, In the tables that follow, and repre-
       sent the values stored in these registers.  represents the value of the argument supplied to the function.

       The following table lists the function escapes:

       Escape	  Argument   Returns   Interpretation
       msg		     integer   message number
       cur		     integer   message is current
       size		     integer   size of message
       strlen		     integer   length of str
       width		     integer   output buffer size in bytes
       charleft   integer    integer   space left in output buffer
       timenow		     integer   seconds since the epoch
       me		     string    the user's mailbox
       eq	  literal    integer   num == arg
       ne	  literal    integer   num != arg
       gt	  literal    integer   num > arg
       match	  literal    boolean   str contains arg
       amatch	  literal    boolean   str starts with arg
       plus		     integer   arg plus num
       minus		     integer   arg minus num
       divide	  literal    integer   num divided by arg
       num	  literal    integer   Set num to arg
       lit	  literal    integer   Set str to arg
       nonzero	  expr	     integer   num is non-zero
       zero	  expr	     integer   num is zero
       null	  expr	     integer   str is empty
       nonnull	  expr	     integer   str is non-empty
       void	  expr		       Set str or num
       comp	  comp	     string    Set str to component text
       compval	  comp	     integer   num set to atoi(str)
       trim	  expr		       trim trailing white space from str
       putstr	  expr		       print str
       putstrf	  expr		       print str in a fixed width
       putnum	  expr		       print num
       putnum	  expr		       print num in a fixed width

       The following functions require a date component as an argument:

       Escape	    Argument   Returns	 Interpretation
       sec	    date       integer	 seconds of the minute
       min	    date       integer	 minutes of the day
       hour	    date       integer	 hours of the day (24 hour clock)
       wday	    date       integer	 day of the week (Sunday=0)
       day	    date       string	 day of the week
       weekday	    date       string	 day of the week (long)
       sday	    date       integer	 day of the week known
					 1 for explicit in date
					 0 for implicit
					 -1 for unknown
       mday	    date       integer	 day of the month
       yday	    date       integer	 day of the year
       mon	    date       integer	 month of the year
       month	    date       string	 month of the year (abbreviated)
       lmonth	    date       string	 month of the year (long form)
       year	    date       integer	 year of the century

       zone	    date       integer	 timezone in hours
       tzone	    date       string	 timezone as a string
       szone	    date       integer	 timezone explicit?
					 1 for explicit
					 0 for implicit
					 -1 for unknown
       date2local   date		 coerce date to local timezone
       date2gmt     date		 coerce date to GMT
       dst	    date       integer	 daylight savings in effect?
       clock	    date       integer	 seconds since the epoch
       rclock	    date       integer	 seconds prior to current time
       tws	    date       string	 official RFC 822 rendering of the date
       pretty	    date       string	 a more user-friendly rendering
       nodate	    date		 str could not be parsed as a date

       The following functions require an address component as an argument.  Some functions return a value based on the first address in the field
       only.  These are indicated by the note (first only).

       Escape	    Argument   Returns	 Interpretation
       proper	    addr       string	 official RFC 822 rendering
					 of the address
       friendly     string     string	 a more user-friendly
       pers	    addr       string	 the personal name (first only)
       note	    addr       string	 commentary text (first only)
       mbox	    addr       string	 the local part of the address
					 (first only)
       mymbox	    addr		 does the address refer to
					 the user's mailbox?
					 (0=no, 1=yes)
       host	    addr       string	 the domain part of the address
					 (first only)
       nohost	    addr       integer	 no host was present in the address
					 (first only)
       type	    addr       integer	 the type of host
					 -1 for uucp
					 0 for local
					 1 for network
					 2 for unknown
       path	    addr       string	 the route part of the address
					 (first only)
       ingrp	    addr       integer	 the address appeared inside a group
					 (first only)
       gname	    addr       string	 name of the group (first only)
       formataddr   expr		 append arg to str as
					 an address list
       putaddr	    literal		 print str address list with arg
					 as an optional label; get line width
					 from num

       Some  functions	that  print their arguments can be controlled by giving field width arguments.	The functions and print their arguments as
       specified by the field width arguments.	So will print the message size in six digits, filled with leading  zeros;  will  print	the  From:
       header  field in 14 characters, with trailing spaces as required.  With supplying a negative field width will cause the string to be right-
       justified within the field.  The functions and ignore any field width arguments, and print their arguments in the minimum number of charac-
       ters required.

       When  the  friendly  format for addresses is used, addresses longer than about 180 characters are truncated to an empty string.	This means
       that such addresses will not appear in the display.

       The function checks each of the addresses in the named header component against the user's mailbox name, and against  any  other  mailboxes
       listed  in the Alternate-Mailboxes entry in the user's It returns true if any of the address matches.  However, it also returns true if the
       named header field is not present.  If necessary, you can use the or functions to test explicitly for the presence of the field.

       The default format string for follows.  This has been divided into several pieces for readability.  The first part is:
       %4(msg)%<(cur)+%| %>%<{replied}-%| %>
       This means that the message number should be printed in four digits; if the message is the current message then a is printed.  If the  mes-
       sage  is not the current message, then a space is printed.  If a Replied: field is present, a is printed.  If no Replied: field is present,
       then a space is printed.  Next:
       The month and date are printed in two digits (zero filled).  Next:
       %<{date} %|*>
       If no Date: field is present, then a is printed, otherwise a space.  Next:
       If the message is from me, print To: followed by a user-friendly rendering of the first address in the To: field.
       If the message is not from me, then the From: address is printed.  And finally:
       The subject and initial body are printed preceded by the string <<.

       Although this seems complicated, this method is flexible enough to extract individual fields and print them in any format the user desires.

       If the -form formatfile switch is given with the command, it will treat each line in the named file as a format	string,  and  act  accord-
       ingly.  This lets the user develop template listing formats.  Some examples can be found in and

See Also
       scan(1mh), ap(8mh), dp(8mh)

Man Page