Rational ClearCase Commands Referenceannotate
apropos
catcr
catcs
cc.icon
cc.magic
cd
chactivity
chbl
checkin
checkout
checkvob
chevent
chflevel
chfolder
chmaster
chpool
chproject
chstream
chtype
chview
clearaudit
clearbug
cleardescribe
cleardiffbl
cleardiff
clearexport_ccase
clearexport_cvs
clearexport_pvcs
clearexport_rcs
clearexport_sccs
clearexport_ssafe
clearfsimport
cleargetlog
clearhistory
clearimport
clearjoinproj
clearlicense
clearmake
clearmake.options
clearmrgman
clearprojexp
clearprompt
cleartool
clearviewupdate
clearvobadmin
comments
config_ccase
config_spec
cptype
credmap
creds
deliver
describe
diffbl
diffcr
diff
dospace
edcs
endview
env_ccase
events_ccase
export_mvfs
exports_ccase
file
find
findmerge
fmt_ccase
getcache
get
getlog
help
hostinfo
init_ccase
ln
lock
lsactivity
lsbl
lscheckout
lsclients
lscomp
lsdo
lsfolder
lshistory
ls
lslock
lsmaster
lspool
lsprivate
lsproject
lsregion
lsreplica
lssite
lsstgloc
lsstream
lstype
lsview
lsvob
lsvtree
makefile_aix
makefile_ccase
makefile_gnu
makefile_pmake
makefile_smake
makefile_sun
man
merge
mkactivity
mkattr
mkattype
mkbl
mkbranch
mkbrtype
mkcomp
mkdir
mkelem
mkeltype
mkfolder
mkhlink
mkhltype
mklabel
mklbtype
mkpool
mkproject
mkregion
mkstgloc
mkstream
mktag
mktrigger
mktrtype
mkview
mkvob
mount_ccase
mount
msdostext_mode
mvfslog
mvfsstorage
mvfstime
mvfsversion
mv
omake
pathnames_ccase
permissions
profile_ccase
promote_server
protect
protectvob
pwd
pwv
query_language
quit
rebase
recoverview
reformatview
reformatvob
register
relocate
rename
reqmaster
reserve
rgy_backup
rgy_check
rgy_passwd
rgy_switchover
rmactivity
rmattr
rmbl
rmbranch
rmcomp
rmdo
rmelem
rmfolder
rmhlink
rmlabel
rmmerge
rmname
rmpool
rmproject
rmregion
rmstgloc
rmstream
rmtag
rmtrigger
rmtype
rmver
rmview
rmvob
schedule
schemes
scrubber
setactivity
setcache
setcs
setplevel
setsite
setview
shell
snapshot.conf
softbench_ccase
space
startview
type_manager
umount
uncheckout
unlock
unregister
unreserve
update
version_selector
view_scrubber
vob_restore
vob_scrubber
vob_sidwalk
vob_snapshot
vob_snapshot_setup
wildcards_ccase
winkin
xclearcase
xcleardiff
xmldiffmrg
DESCRIPTION
The protect command sets the owner, group, or permissions for one or more elements, shared derived objects, or named VOB objects. This information is maintained in the VOB database.
Note: This command does not apply to files loaded in a snapshot view.
The main use of protect is to control access by standard programs to an element or object's data. For example, you can make some elements readable by anyone and make others readable by only their group members.
Modifying the permissions of an element changes the permissions of all of its source containers and (if applicable) its cleartext containers. That is, the change affects all versions, not just the version selected by the current view. There is no way to change the permissions of an individual version.
Some forms of protect affect ClearCase and ClearCase LT access. For example, a checkout or checkin is permitted only if the user is the element's owner or is a member of the element's group.
View-Private Objects
This command does not affect view-private objects. For this reason, entering a protect command sometimes seems to have no effect:
- Changing an element's permissions has no effect on its checked-out versions. After you check in the element, your view selects the checked-in version, thus making the updated permissions appear.
- Changing a DO's permission has no effect on the way the DO appears in the view where it was originally created or in the dynamic views where it has been winked in. To have your dynamic view use a shared DO with updated permissions:
You can change the permissions on any view-private object (including a checked-out version), with the standard operating system commands.
Note: For UNIX users, we support the BSD semantics (POSIX CHOWN RESTRICTED) for chown: only root can change the owner IDs. (In a view, this means the root identity on the machine on which the view storage directory resides.)
A winked-in DO is not really a view-private object, but it behaves like one (so that users in different views can build software independently). Moreover, changing the permissions of a winked-in DO actually converts it to a view-private file in your view. See Building Software.
Owner Setting
The initial owner of an element is the user who creates it with mkelem or mkdir. The initial owner of a named VOB object is the user who creates it. The initial owner of a derived object is the user who builds it with clearmake. When the derived object is winked in and becomes shared, its data container is promoted to a VOB storage pool. This process preserves the derived object's ownership, no matter who performs the build that causes the winkin.
For a list of operations that can be performed by an element's owner, see the permissions reference page .
Group Setting
The initial group of an element or named VOB object is the principal group of its creator. The new group specified in a protect –chgrp command must be one of the groups on the VOB's group list.
See the permissions reference page for a list of operations that can be performed by members of an element's or derived object's group.
Note: When UNIX users execute protect –chgrp, the setuid and setgid bits of the file mode (04000 and 02000, respectively) are always cleared. This behavior differs from UNIX practice, where clearing occurs only when a non-root identity runs the chgrp command.
Read and Execute Permissions
The read and execute permissions of an element or a shared derived object control access to its data in the standard manner. The permissions are also applied to all its associated data containers.
Note: protect sometimes adds group-read permission to your specification to ensures that the owner of an element always retains read permission to its data containers.
Write Permission
The meaning of the write permission varies with the kind of object:
- For a file element, write permission settings are ignored. To obtain write permission to a file element, you must check it out (see the checkout reference page).
- For a directory element, write permission allows view-private files to be created within it. ClearCase or ClearCase LT permissions control changes to the directory element itself. (See the permissions reference page.)
- For a shared derived object, write permission allows it to be overwritten with a new derived object during a target rebuild. (The shared derived object is not actually affected; rather, the view sees the new, unshared derived object in its place.)
Protection of Global Types and Local Copies
Changing the protection of a global type or a local copy of a global type changes the protection of the global type and all its local copies. You must have permission to change the protection of the global type.
If the protection cannot be changed on one or more of the local copies, the operation fails and the global type's protection is not changed. You must fix the problem and run the protect command again.
For more information, see the Administrator's Guide.
RESTRICTIONS
Identities
You must have one of the following identities:
- Object owner
- VOB owner
- root (UNIX)
- Member of the ClearCase administrators group (ClearCase on Windows)
- Local administrator of the ClearCase LT server host (ClearCase LT on Windows)
Note: For protect –chgrp, you must be a member of the new group, and it must also be in the VOB's group list.
Locks
An error occurs if one or more of these objects are locked: VOB, element type, element, pool (nondirectory elements only). For named objects, an error occurs if the VOB, object, or object's type is locked.
Mastership
(Replicated VOBs only) If your current replica preserves identities and permissions, it must master the object being processed. If your current replica preserves permissions only and you use the –chmod option, your replica must master the object being processed. If your current replica preserves permissions only and you do not use the –chmod option, or your current replica is nonpreserving, no mastership restrictions apply.
OPTIONS AND ARGUMENTS
Specifying Permission Changes
- Default
- None.
- –cho·wn login-name
- New owner for the elements or VOB objects.
UNIX: The argument must be in chown(1) format. The owner may be either a decimal user ID or a login name found in the passwd(4) file.
Windows: The login-name must specify a domainwide user account.
- –chg·rp group
- New group for the elements or VOB objects.
UNIX: The argument must be in chgroup(1) format. The group may be either a decimal group ID or a group name found in the group(4) file.
Windows: The group must be registered in the domainwide account database.
- –chm·od permissions
- New permissions—owner, group, other
(world)—for the elements or VOB objects. Both symbolic and absolute
codes are valid, such as go–x (symbolic) or 666 (absolute).
Following is a summary (UNIX users may read chmod(1) for
details):
Specify symbolic permissions in one or more of the following forms:
[identity]+permission
[identity]-permission
[identity]=permission
where identity is any combination of
When identity is unspecified, its default value is a.
permission can be any combination of
To combine the forms, separate them with a comma (no white space). For example, to specify read and write permissions for an element's owner and no access by group or other:
cmd-context protect –chmod u=rw,go-rwx test.txt
Absolute permissions are constructed from the OR of any of the following octal numbers:
For example, the value 600 specifies read/write permission for the owner and no access by any other identity. The value 764 gives all permissions to the owner, read/write permissions to the group, and read permission to others.
Event Records and Comments
- Default
- Creates one or more event records, with
commenting controlled by your .clearcase_profile file
(default: –nc). See the comments reference
page. Comments can be edited with chevent.
- –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach | –nc·omment
- Overrides the default with the option you
specify. See the comments reference page.
Specifying the Objects
- Default
- None.
- –fil·e
- Restricts the command to changing file elements
only. This option is especially useful in combination with the –recurse option.
- –d·irectory
- Restricts the command to changing directory
elements only. This option is especially useful in combination with the –recurse option.
- [ –pna·me ] pname ...
- One or more pathnames, each of which specifies
an element or shared derived object. If pname has
the form of an object selector, you must use the –pname option
to indicate that pname is a pathname. An extended
pathname to a version or branch is valid, but keep in mind that protect affects
the entire element. Shared derived objects can be referenced by DO ID.
If you specify multiple pname arguments, but you do not have permission to change the permissions on a particular object, protect quits as soon as it encounters this error.
- object-selector ...
- One or more named VOB objects. Specify object-selector in
one of the following forms:
Processing of Directory Elements
- Default
- Any pname argument
that specifies a directory causes the directory element itself to be changed.
- –r·ecurse
- Changes the entire tree of elements including
and below any pname argument specifying a directory
element. UNIX VOB symbolic links are not traversed during the recursive descent.
(Use –file or –directory to
restrict the changes to one kind of element.)
EXAMPLES
The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.
The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.
In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.
- Add read permission to the file element hello.c, for all users.
- Change the group ID for all elements in the src directory to user.
- Change the owner of the branch type qa_test to tester.
- Allow users in the same group to read/write/execute the shared derived object hello, but disable all access by others. Use an absolute permission specification.