unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



mcs(1)								       mcs(1)



NAME

  mcs -	Manipulates object file	comment	sections

SYNOPSIS

  mcs [-v] [-V]	[[-a|r|R  data]	| [-D key] | [-d] ] [-t	tag] [-g flags]	[-p]
  obj1...objN

OPTIONS

  -a data
      Add a new	subsection or append to	existing subsection data. By default,
      the data is treated as a character string	and appended to	the generic
      string space subsection. Use -t to specify a subsection.

  -d  Delete a subsection. Use -t to specify the subsection that you want to
      delete.

  -D key
      Delete one entry within a	subsection. Use	-t to specify the subsection
      that this	operation applies to. Currently, this option can only be used
      with the system subsections TAGDESC and TOOLVER.

  -g flags
      Set tag descriptor flags for a subsection. Use -t	to specify the sub-
      section. If flag settings	already	exist for this tag value, they are
      overwritten by the new settings.

  -p  Print a subsection or the	entire comment section.	By default, the	whole
      section is dumped. Use -t	to specify a subsection. By default, raw data
      is dumped	in hexadecimal.	Special	formatting can be used for system-
      defined subsections.

      Use with -v to view contents symbolically.

      This option produces the same output as odump -cm. Use odump -j to view
      compact relocations data stored in the comment section.

  -r data
      Replace subsection data. Use -t to specify the subsection	that you want
      to replace. The same data	interpretation applies to both -r and -a.

  -R data
      Replace one entry	of a subsection	with the given data. Use -t to
      specify the subsection that this applies to. Currently, this option can
      only be used with	the system subsections TAGDESC and TOOLVER.

  -t tag
      Specify subsection. Within an object, a tag is a unique identifier;
      only one subsection is permitted of each tag type.

  -v  Produce verbose output. Can be used with -p.

  -V  Print version information	for the	mcs tool.





OPERANDS

  data
      Character	string.	 Character strings containing white space must be
      enclosed in quotes.

      For certain subsections, specially formatted data	is accepted. See Spe-
      cial Sections for	more information.

  key Unique identifier	for an entry within a subsection. See Special Sec-
      tions for	more information.

  tag An unsigned integer value	or a system-defined tag	name.

  flags
      Comma-separated tag descriptor flag names. See Special Sections for
      more information.

  obj A	Tru64 UNIX object file that contains a comment section header.
      Archive files are	not supported. The object file can be a	.o file, an
      executable, or a shared library. It can be either	compressed or
      uncompressed.

DESCRIPTION

  The mcs command allows users to perform operations on	the comment section
  (.comment) of	Compaq (e)COFF object files. The comment section of an object
  can contain information such as the "ident" string from a source file	and
  other	information used by components of the Tru64 UNIX development environ-
  ment.	Users can optionally add their own information to the comment section
  by using the mcs tool.

  Special Symbols


  Definitions for symbols related to the comment section are located in
  /usr/include/scncomment.h. The symbols recognized by mcs are shortened
  forms	of the names defined in	the header file.  The symbols consist of the
  names	of system-defined tags and tag descriptor flags.

  System-defined tag names can be used with the	-t option to specify a sub-
  section. These tags are:

       CMSTAMP
       COMPACT_RLC
       STRSPACE
       TAGDESC
       IDENT
       TOOLVER
       LINKERDEF

  Tag descriptor flag names can	be used	with the -g option to specify how
  other	tools should treat a specified subsection. The flag names recognized
  by mcs are:

       KEEP
       STRIP
       LSTRIP
       APPEND
       CHOOSE
       DELETE
       ERRMULT
       ERROR
       COPY

  See Special Sections for more	information on the TAGDESC and TOOLVER sub-
  sections.

  Special Sections


  Processing of	the TAGDESC and	TOOLVER	subsections differs from other sec-
  tions	due to the following factors:

   1.  The -R and -D options can be used for per-entry operations.

   2.  The data	entry format is	unique.

  TAGDESC Processing
      System tools that	create or modify objects rely on tag descriptor	flags
      in the TAGDESC section to	know how to process subsections	that are not
      recognized by the	tool. This allows new subsection types to be added
      without requiring	changes	to system tools	that control how they process
      the new subsections.

      Three sets of flags are supported:


      _________________________
      Strip    Combine	 Modify
      _________________________
      KEEP     APPEND	 COPY
      STRIP    CHOOSE	 DELETE
      LSTRIP   DELETE	 ERROR
	       ERRMULT
	       ERROR
      _________________________

      The "strip" flags	tell the linker	or stripping tools what	subsections
      belong in	a stripped or locally-stripped object:

	+  KEEP	means do not strip.

	+  STRIP means delete if removing the symbol table.

	+  LSTRIP means	delete if removing local symbol	information.

      The "combine" flags tell tools such as the linker	and mcs	how to com-
      bine data	from multiple input subsections	of the same type:

	+  APPEND means	to concatenate raw data	for each subsection.

	+  CHOOSE means	to choose one (random) subsection's data.

	+  DELETE tells	the tools that this subsection does not	belong in an
	   output object.

	+  ERRMULT means raise an error	if multiple instances of the tag
	   value are found.

	+  ERROR means raise an	error if the tag value identifies an unknown
	   subsection type.

      The "modify" flags tell a	tool that is modifying a single	object what
      to do with subsections it	does not understand:

	+  COPY	means output a subsection identical to the one found in	the
	   input object.

	+  DELETE means	do not output the subsection.

	+  ERROR means raise an	error if a subsection of this type is encoun-
	   tered.

      One value	from each set is defined for each subsection. The default
      flag settings are	KEEP, APPEND, COPY.

      Flags are	specified symbolically on the command line. The	accepted for-
      mat is a comma-separated list of three flag names	with no	white space.
      For example, the default flag setting for	a subsection with the tag
      TAG# is specified	as follows:


	   mcs -t TAG# -gKEEP,APPEND,COPY obj

      The key for a TAGDESC entry is the tag value being described.

  TOOLVER Processing
      The TOOLVER subsection accepts data of the form:

      tool_name,tool_version_number,version_string

      The variables tool_name and version_string are character strings,	and
      tool_version_number is a numeric value. For example, to add tool ver-
      sion information for a program named mytool, the command is:


	   mcs -t TOOLVER -a "mytool,0,\"Beta, 1/1/99\ obj

      This creates a new entry for the tool named mytool in the	TOOLVER	sub-
      section. To update this entry, use the -R	option:


	   mcs -t TOOLVER -R "mytool,1,\"SSB, 1/1/99\ obj

      Note that	double quotes have to be passed	through	the shell for strings
      containing white space or	commas.	Make sure that the separator commas
      have no spaces around them.

      The key for the TOOLVER entry is the tool	name.

EXAMPLES

  The comment section of an executable file might appear as follows:

       % mcs -pv objname

	  Tag		 Length	     Value     Flags: Strip Combine Modify
	  CMSTAMP	 0x0	     0x0	      KEEP CHOOSE COPY
	  COMPACT_RLC	 0x208	     0x30	      STRIP DELETE DELETE

	       --- freeform data ---		    Use	odump -j to view compact relocations.

	       ---- end	data ---   END		  0x0	      0x0	       KEEP CHOOSE COPY

  If you want to delete	compact	relocations:

       % mcs -d	-t COMPACT_RLC objname

  If you want to add a subsection and specify flags for	it:

       % mcs -a	DATA -t10 -g STRIP,APPEND,COPY objname

  The new subsection, identified by a tag value	of 10, contains	the string
  "DATA" in its	associated freeform data. The flag settings indicate that the
  section should be stripped if	the symbol table is removed, have data
  appended if objects with this	section	are linked or otherwise	combined, and
  left unchanged by an object modifier.

ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of mcs:

  TMPDIR
      If set, this path	is used	for the	creation of a temporary	file. A	tem-
      porary file is used if an	input object is	compressed.

SEE ALSO

  Commands:  odump(1)