unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



get(1)								       get(1)



NAME

  get -	Creates	a specified version of a Source	Code Control System (SCCS)
  file

SYNOPSIS

  get [-g] [-L]	[-m] [-n] [-p] [-s] [-t] [-c cutoff] [-i list] [-r SID]	[-w
  string] [-x list] file... | -

  get [-a seq_num] [-b]	[-e] [-k] [-s] [-t] [-c	cutoff]	[-i list] [-r SID]
  [-x list] [-l	 | -lp]	file...	| -

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  get:	XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPTIONS

  -a seq_num
      [Tru64 UNIX]  Specifies the delta	sequence number	of the SCCS file
      delta (version) that is be retrieved.  This keyletter is used by the
      comb command.

  -b  Specifies	that the delta to be created should have a SID in a new
      branch.  The new SID is numbered according to the	rules stated in	the
      SID Determination	Table.	You can	use -b only with the -e	option.	 It
      is only necessary	when you want to branch	from a leaf delta (a delta
      without a	successor).  Attempting	to create a delta at a nonleaf delta
      automatically results in a branch, even if the b header flag is not
      set.  If you do not specify the b	header flag in the SCCS	file, get
      ignores the -b option because the	file does not allow branching.

  -c cutoff
      Specifies	a cutoff date and time,	in the form: yy[mm[dd[hh[mm[ss]]]]].
      The get command includes no deltas to the	SCCS file created after	the
      specified	cutoff in the g-file.  The values of any unspecified items in
      cutoff default to	their maximum allowable	values.	 Thus, a cutoff	date
      and time specified with only the year (yy) would specify the last
      month, day, hour,	minute,	and second of that year.  Any number of	non-
      numeric characters can separate the 2-digit items	of the cutoff date
      and time.	 This lets you specify a date and time in a number of ways,
      as follows:
	   -c90/9/2,9:00:00
	   -c"90/9/2 9:00:00"
	   "-c90/9/2 9:00:00"

      [Tru64 UNIX]  If the year	(yy) field is less than	69 get interprets it
      as being in the twenty-first century, i.e. 20yy. If the year is greater
      than or equal to 69, get interprets it as	being in the twentieth cen-
      tury, i.e. 19yy.

  -e  Indicates	that the g-file	being created is to be edited by the user
      applying get.  The changes are recorded later with the delta command.
      The get -e command creates a p-file that prevents	other users from
      issuing another get -e and editing a second g-file on the	same SID
      before delta is run.  The	owner of the file can override this restric-
      tion by allowing joint editing on	the same SID through the use of	the
      admin command with the -fj option.  Other	users, with permission,	can
      obtain read-only copies by using get without the -e option.  The get -e
      command enforces SCCS file protection specified via the ceiling, floor,
      and authorized user list in the SCCS file	(see the admin(1) reference
      page).

  -g  Suppresses the actual retrieval of text from the SCCS file.  Use the -g
      option primarily to create an l-file or to verify	the existence of a
      particular SID.  Do not use it with the -e option.

  -i list
      Specifies	a list of deltas to be included	in the creation	of a g-file.
      The SID list format consists of a	combination of individual SIDs
      separated	by commas and SID ranges indicated by two SIDs separated by a
      hyphen, as shown in the following	example:
	   get -e -i1.4,1.5,1.6	s.file

	   get -e -i1.4-1.6 s.file

      You can specify the SCCS Identification of a delta in any	form shown in
      the SID Specified	column of the SID Determination	Table.	The get	com-
      mand interprets partial SIDs as shown in the SID Retrieved column	of
      the table.

  -k  Suppresses replacement of	identification keywords	in the g-file by
      their values.  The -k option is implied by the -e	option.	 If you
      accidentally ruin	the g-file created by get with an -e option, you can
      recreate it by reissuing the get command with the	-k option in place of
      the -e option.

  -l[p]
      Writes a delta summary to	an l-file.

      If you specify -lp, get interprets it as -L. The -lp option is
      obsolete.

  -L  Writes a delta summary to	standard output	and does not create an l-
      file.  All informative output that normally is written to	standard out-
      put is written to	standard error instead,	unless the -s option is
      specified, in which case it is suppressed.  Use this option to deter-
      mine which deltas	were used to create the	g-file currently in use.

  -m  Writes before each line of text in the g-file the	SID of the delta that
      inserted the line	into the SCCS file.  The format	is as follows:

      SID tab line_of_text

  -n  Writes the value of the %M% keyword before each line of text in the g-
      file.  The format	is the value of	%M%, followed by a horizontal tab,
      followed by the text line.  When both the	-m and -n options are used,
      the format is as follows:

      %M%_value	tab  SID  tab  line_of_text

  -p  Writes the text created from the SCCS file to standard output and	does
      not create a g-file.  The	get command sends output normally sent to
      standard output to file descriptor 2 (standard error) instead.  If you
      specify the -s option with the -p	option,	output normally	sent to	stan-
      dard output does not appear anywhere.  Do	not use	-p with	the -e
      option.

  -r SID
      Specifies	the SCCS identification	string (SID) of	the SCCS file version
      to be created.  Shows what version of a file is created and the SID of
      the pending delta	as functions of	the SID	specified.

  -s  Suppresses all output normally written to	standard output.  Error	mes-
      sages (written to	standard error)	remain unaffected.

  -t  Accesses the most	recently created delta in a given release or release
      and level.  Without the -r option, get accesses the most recent delta
      regardless of its	SID.

  -w string
      [Tru64 UNIX]  Substitutes	string for the %W% keyword in g-files not
      intended for editing.

  -xlist
      Excludes a list of deltas	in the creation	of a file.  See	the -i option
      for the SID list format.

OPERANDS

  file
      The path name of an existing SCCS	file or	directory.

      The options and files can	be specified in	any order, and all options
      apply to all named files.	 If you	specify	a directory in place of	file,
      get performs the requested actions on all	the files in the directory
      that begin with the s. prefix.  If you specify a - (dash)	in place of
      file, get	reads standard input and interprets each line as the name of
      an SCCS file. The	get command continues to read input until it reads an
      End-of-File character.

DESCRIPTION

  The get command reads	the specified versions of the named SCCS files,	and
  creates a text file (the g-file), for	each file according to the specified
  options. The command then writes each	text file to a file with the same
  name as the original SCCS file without the s.	(s period) prefix.

  If the effective user	has write permission in	the directory containing the
  SCCS files but the real user does not, then only one file can	be named when
  the -e option	is used.

  SCCS Files


  In addition to the file with the s. prefix (the s-file), get can create
  several auxiliary files:  the	g-file,	l-file,	p-file,	and z-file.  These
  files	are identified by their	tag, which is the letter before	the dash.
  The get command names	auxiliary files	by replacing the leading s. in the
  SCCS file name with the proper tag, except for the g-file, which is named
  by removing the s. prefix.  So, for a	file named s.sample, the auxiliary
  file names would be sample, l.sample,	p.sample, and z.sample.

  These	files serve the	following purposes:

  s-file
      Contains the original file text and all the changes (deltas) made	to
      the file.	 It also includes information about who	can change the file
      contents,	who has	made changes, when those changes were made, and	what
      the changes were.	 You cannot edit this file directly, because the file
      is read-only.  It	contains the information needed	by the SCCS commands
      to build the g-file, the file you	can edit.

  g-file
      A	text file that contains	the text of the	SCCS file version that you
      specify with the -r option (or the latest	trunk version by default).
      You can edit this	file directly.	When you have made all your changes
      and you want to make a new delta to the file, you	can then apply the
      delta command to the file.  The get command creates the g-file in	the
      current directory.

      The get command creates a	g-file whenever	it runs, unless	the -g option
      or the -p	option is specified.  The real user owns it (not the effec-
      tive user).  If you do not specify the -k	or the -e option, the file is
      read-only.  If the -k or the -e option is	specified, the owner has
      write permission for the g-file.	You must have write permission in the
      current directory	to create a g-file.

  l-file
      The get command creates the l-file (a read-only file) when the -l
      option is	specified.  It contains	a table	showing	which deltas were
      applied in generating the	g-file.	 You must have write permission	in
      the current directory to create an l-file.

      Lines in the l-file have the following format:

	+  A space if the delta	was applied; an	* (asterisk) appears other-
	   wise.

	+  A space if the delta	was applied or was not applied and ignored;
	   an *	appears	if the delta was not applied and was not ignored.

	+  A code indicating a special reason why the delta was	or was not
	   applied:

	   space
	       Included	or excluded normally.

	   I   Included	using the -i option.

	   X   Excluded	using the -x option.

	   C   Cut off using the -c option.

	+  The SID.

	+  The date and	time the file was created.

	+  The user name of person who created the delta.

	   Comments and	MR data	follow on subsequent lines, indented one hor-
	   izontal tab character.  A blank line	ends each entry.

	   For example,	for a delta cut	off with the -c	option,	the entry in
	   the l-file might be:
		**C 1.3	90/03/13 12:44:16 pat

	   The entry for the initial delta might be:
		1.1 90/02/27 15:42:20 pat
		date and time created 90/02/27 15:42:20	by pat



  p-file
      The get command creates the p-file when the -e or	the -k option is
      specified.  The p-file passes information	resulting from a get -e	to a
      delta command. The p-file	also prevents a	subsequent execution of	get
      with an -e option	for the	same SID until delta is	run or the joint edit
      keyletter	(j) is set in the SCCS file.  The j keyletter allows several
      gets on the same SID.  The p-file	is created in the directory
      containing the SCCS file.	 To create a p-file in the SCCS	directory,
      you must have write permission in	that directory.	 The permission	code
      of the p-file is read-only to all	but its	owner, and it is owned by the
      effective	user.

      The p-file contains:

	+  The current SID.

	+  The SID of new delta	to be created.

	+  The user name.

	+  The date and	time of	the get.

	+  The -i option, if it	was present.

	+  The -x option, if it	was present.

      The p-file contains an entry with	the preceding information for each
      pending delta for	the file.  No two lines	have the same new delta	SID.

  z-file
      The z-file is a lock mechanism against simultaneous updates.  It con-
      tains the	binary process number of the get command that created it.  It
      is created in the	directory containing the SCCS file and exists only
      while the	get command is running.

  When you use the get command,	it displays the	SID being accessed and the
  number of lines created from the SCCS	file.  If you specify the -e option,
  the SID of the delta to be made appears after	the SID	accessed and before
  the number of	lines created.	If you specify more than one file, or a
  directory, or	standard input,	get displays the file name before each file
  is processed.	 If you	specify	the -i option, get lists included deltas
  below	the word Included.  If you specify the -x option, get lists excluded
  deltas below the word	Excluded.

  Getting Read-Only File Versions


  [Tru64 UNIX]	The get	command	creates	read-only versions as well as edit-
  able versions	of a file.  Use	read-only versions of files any	time the
  application does not require that the	file contents be changed.  Read-only
  versions of source code files	can be compiled. Text files can	be displayed
  or printed from read-only versions.

  [Tru64 UNIX]	The difference between an editable version and a read-only
  version is important when using identification keywords.  Identification
  keywords are symbols that are	expanded to some text value when the get com-
  mand retrieves the file as read-only.	 In editable versions, keywords	are
  not expanded.	 Identification	keywords can appear anywhere in	an SCCS	file
  (see the prs(1) reference page for further information on identification
  keywords).








  Identification Keywords


  You can use identification keywords in your files to insert identifying
  information.	These keywords are replaced by their values in the g-file
  when get is invoked without the -e or	-k option.  The	following identifica-
  tion keywords	can be used in SCCS files:

  Identifying Values:

  %M% Module name: the value of	the m flag in the SCCS file with the leading
      s. removed

  %I% The SID (%R%.%L%.%B%.%S%)	of the g-file

  %R% Release

  %L% Level

  %B% Branch

  %S% Sequence

  %D% Date of the current get (yy/mm/dd)

  %H% Date of the current get (mm/dd/yy)

  %T% Time of the current get (hh:mm:ss)

  %E% Date newest applied delta	was created (yy/mm/dd)

  %G% Date newest applied delta	was created (mm/dd/yy)

  %U% Time newest applied delta	was created (hh:mm:ss)

  Names:

  %F% SCCS file	name

  %P% Full path	name of	the SCCS file

  Flag Value:

  %Q% The value	of the q flag in the file

  %Y% Module type: the value of	the t flag in the SCCS file

  Line Number:

  %C% The current line number.	This keyword is	for identifying	messages out-
      put by the program.  It is not intended for use on every line to pro-
      vide sequence numbers.

  Constructing what Strings:

  %W% A	shorthand notation for constructing what strings of the	following
      type. Its	value is the characters	and keyletters:


	   %W% = %Z%%M%<tab>%I%

  %Z% The 4-character string @(#) recognized by	the what command.

  %A% Another shorthand	notation for constructing what strings.	 Its value is
      the keyletters:


	   %A% = %Z%%Y%	%M% %I%%Z%



  The following	table illustrates how get determines the SID of	the file it
  retrieves, and what the pending SID is.  The column SID Specified shows the
  various ways the SID can be specified	with the -r option.  The next two
  columns illustrate the various conditions that can exist, including whether
  or not the -b	option is used with the	get -e.	 The SID Retrieved column
  indicates the	SID of the file	that makes up the g-file.  The SID of Delta
  to be	Created	column indicates the SID of the	version	that will be created
  when delta is	applied.

  SID Determination Table


  ___________________________________________________________________________
  SID Specified	     -b	Used		       SID Retrieved

			       Other Condi-
			       tions


							       SID of
							       Delta to	be
							       Created
  ___________________________________________________________________________
  None (1)	     No			       mR.mL	       mR.(mL+1)

			       R defaults to
			       mR(2)
  None (1)	     Yes		       mR.mL

			       R defaults to
			       mR


							       mR.mL.(mB+1).1

  (R)elease	     No			       mR.mL	       R.1 (3)

			       R > mR
  R		     No	       R = mR	       mR.mL	       mR.(mL+1)
  R		     Yes		       mR.mL

			       R > mR

							       mR.mL.(mB+1).1
  R		     Yes       R = mR	       mR.mL

							       mR.mL.(mB+1).1
  R		     N/A		       hR.mL (4)

			       R < mR and R
			       does not
			       exist



							       hR.mL.(mB+1).1


  R		     N/A		       R.mL

			       R < mR and R
			       exists


							       R.mL.(mB+1).1

  R.(L)evel	     No			       R.L	       R.(L+1)

			       No trunk	suc-
			       cessor
  R.L		     yes		       R.L	       R.L(mB+1).1

			       No trunk	suc-
			       cessor
  R.L		     N/A		       R.L

			       Trunk succes-
			       sor in
			       release >= R



							       R.L.(mB+1).1


  R.L.(B)ranch	     No			       R.L.B.mS

			       No branch
			       successor


							       R.L.B.(mS+1)

  R.L.B		     Yes		       R.L.B.mS

			       No branch
			       successor


							       R.L.(mB+1).1

		     No			       R.L.B.S	       R.L.B.(S+1)

  R.L.B.(S)equence

			       No branch
			       successor
  R.L.B.S	     Yes		       R.L.B.S

			       No branch
			       successor


							       R.L.(mB+1).1

  R.L.B.S	     N/A		       R.L.B.S

			       Branch suc-
			       cessor


							       R.L.(mB+1).1

  ___________________________________________________________________________

  (1) Applies only if the d (default SID) flag is not present in the file
  (see admin(1)	reference page).

  (2) The mR indicates the maximum existing release.

  (3) Forces creation of the first delta in a new release.

  (4) The hR is	the highest existing release that is lower than	the speci-
  fied,	nonexistent, release R.



NOTES

  The obsolescent form of the -l option	uses the optional option-argument
  that cannot be presented as a	separate argument (-lp). When the -l and -p
  options are both needed, the you should avoid	ambiguity by giving them as
  separate arguments (-l -p), reversing	their sequence (-pl) or	separating
  them with other options in a single argument (such as	-ltp).

EXIT STATUS

  The following	exit values are	returned:

  0   Successful completion.

  >&gt;0  An error occurred.

EXAMPLES

  The following	examples and descriptions illustrate the differences between
  read-only and	editable versions of SCCS files.

   1.  To insert the current date and SID in a file, enter the following sym-
       bols in the file:
	    %H%	%I%

       The %H% symbol is for the current date and the %I% symbol is for	the
       SID.  When get retrieves	a file as editable, it leaves the symbols in
       the file	and does not do	text value substitution.

   2.  The following example builds the	version	with the highest SID, because
       no version of the file is specified:
	    $ ls

	    s.test.c

	    $ get s.test.c

	    3.5
	    59 lines

	    $ ls

	    s.test.c test.c



   3.  In the next two command lines, the -r option specifies which version
       to get:
	    $ get -r1.3	s.test.c

	    1.3
	    67 lines

	    $ get -r1.3.1.4 s.test.c

	    1.3.1.4
	    50 lines

   4.  If you specify only the release number of the SID, get finds the	file
       with the	highest	level within that release number:
	    $ get -r2 s.test.c

	    2.7
	    21 lines



   5.  If the SID specified is greater than the	highest	existing SID, get
       retrieves the highest existing SID without complaint.  If the SID
       specified is lower than the lowest existing SID,	SCCS writes an error
       message and fetches nothing.  In	the following example, release 2 is
       the lowest existing release:
	    $ get -r1 s.test.c
	    ERROR [s.test.c]
	    The	SID specified does not exist.
	    Use	the sact command to check the P-file
	    for	existing SID numbers. (cm20)

   6.  The -t option gets the top version in a given release or	level. The
       top version is the most recently	created	delta, independent of its
       location.  In the next example, the highest existing delta in release
       3 is 3.5, while the most	recently created delta is 3.2.1.5:
	    $ get -t -r3 s.test.c

	    3.2.1.5
	    46 lines

       All of the previous examples use	the get	command	to get a read-only
       file.  To create	a copy of the file that	can be edited to create	a new
       delta, use the -e option.  The get command works	differently when
       using the -e option (see	also the admin(1) reference page). Use unget
       to undo the effect of the get -e	command	and discard any	changes	made
       to the file before a delta is created.

   7.  The following example shows how to use the -e option:
	    $ ls

	    s.test.c

	    $ get -e s.test.c

	    1.3
	    new	delta 1.4
	    67 lines

	    $ ls

	    p.test.c s.test.c test.c

       The working file	is test.c.  If you edit	test.c and save	the changes
       with the	delta command, SCCS creates a new delta	with an	SID of 1.4.
       The file	p.test.c is a temporary	file used by SCCS to keep track	of
       file versions.

   8.  In the previous example,	you could have used the	-r option to get a
       specific	version.  Assuming delta 1.3 already exists and	is the
       highest delta in	release, the following three uses of the get command
       produce the same	results:
	    $ get -e s.test.c
	    $ get -e -r1 s.test.c
	    $ get -e -r1.3 s.test.c

   9.  To start	using a	new (higher in value) release number, use get with
       the -r option and specify a release number greater than the highest
       existing	release	number.	 In the	next example, release 2	does not yet
       exist:
	    $ get -e -r2 s.test.c

	    1.3
	    new	delta 2.1
	    67 lines

       Notice that get indicates the version of	the new	delta that will	be
       created if the delta command stores changes to the SCCS file.

       If the example did not include the -e option, get would build the
       highest existing	SID (1.3) and would not	indicate a new delta, even
       though the -r2 option requests a	version	2.1.

   10. To create a branch delta, use the -r option and specify the release
       and level where the branch occurs.  In the next example,	deltas 1.3
       and 1.4 already exist:
	    $ get -e -r1.3 s.test.c

	    1.3
	    new	delta 1.3.1.1
	    67 lines

       Create deltas on	branches using the same	methods.

       Several different editable versions of an SCCS file can exist as	long
       as each one is in a different directory.	 If you	try to get the same
       editable	file version more than once into the same directory without
       using the delta command,	SCCS writes an error message.

       To get the same editable	file version more than once, set the j option
       in the SCCS file	with the admin command.	Set the	j option using the -f
       option.	You can	then get the same SID several times from different
       directories, creating a separate	file for each get command.  Although
       the files originate from	a single SID, SCCS gives each of them a
       unique new SID.

   11. In the following	example, the pwd command displays the current direc-
       tory.  Then the j option	is set with the	admin command:
	    $ pwd

	    /u/dan/sccs

	    $ admin -fj	s.test.c

   12. Then use	the get	command	to retrieve the	latest version of the file:
	    $ get -e s.test.c

	    1.1
	    new	delta 1.2
	    5 lines

   13. Change to directory /u/new and issue the	get command again:
	    $ cd /u/new
	    $ get -e /u/dan/sccs/s.test.c

	    1.1
	    WARNING: 1.1 1.2 dan 90/08/21 09:03:45 is being edited.
	    This if an informational message only. (ge18)
	    new	delta 1.1.1.1
	    5 lines

       Notice that SCCS	creates	two deltas, 1.2	and 1.1.1.1, from the single
       original	file version of	1.1.  The p.test.c file	shows a	separate
       entry for each version currently	in use.	 The p.test.c file remains in
       the directory until you take care of both file versions with either
       the delta command or the	unget command.	(Note that you must have
       write permission	in both	directories to issue the preceding commands.)





ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of get:

  LANG
      Provides a default value for the internationalization variables that
      are unset	or null. If LANG is unset or null, the corresponding value
      from the default locale is used.	If any of the internationalization
      variables	contain	an invalid setting, the	utility	behaves	as if none of
      the variables had	been defined.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_CTYPE
      Determines 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 and input files).

  LC_MESSAGES
      Determines the locale for	the format and contents	of diagnostic mes-
      sages written to standard	error and informative messages written to
      standard output (or standard error if the	-p option is used.

  NLSPATH
      Determines the location of message catalogues for	the processing of
      LC_MESSAGES.

SEE ALSO

  Commands:  admin(1), cdc(1), comb(1),	delta(1), prs(1), rmdel(1), sact(1),
  sccs(1), sccsdiff(1),	sccshelp(1), unget(1), val(1), what(1)

  Files:  sccsfile(4)

  Standards:  standards(5)

  Programming Support Tools