I686LINUX/util/I686LINUX/man/mann/resource.n

   1 '\"
   2 '\" Copyright (c) 1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\" RCS: @(#) $Id: resource.n,v 1.7 2002/07/01 18:24:39 jenglish Exp $
   7 '\"
   8 '\" The definitions below are for supplemental macros used in Tcl/Tk
   9 '\" manual entries.
  10 '\"
  11 '\" .AP type name in/out ?indent?
  12 '\"     Start paragraph describing an argument to a library procedure.
  13 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 '\"     needed;  use .AS below instead)
  17 '\"
  18 '\" .AS ?type? ?name?
  19 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 '\"     name are examples of largest possible arguments that will be passed
  21 '\"     to .AP later.  If args are omitted, default tab stops are used.
  22 '\"
  23 '\" .BS
  24 '\"     Start box enclosure.  From here until next .BE, everything will be
  25 '\"     enclosed in one large box.
  26 '\"
  27 '\" .BE
  28 '\"     End of box enclosure.
  29 '\"
  30 '\" .CS
  31 '\"     Begin code excerpt.
  32 '\"
  33 '\" .CE
  34 '\"     End code excerpt.
  35 '\"
  36 '\" .VS ?version? ?br?
  37 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 '\"     of man pages.  The first argument is ignored and used for recording
  39 '\"     the version when the .VS was added, so that the sidebars can be
  40 '\"     found and removed when they reach a certain age.  If another argument
  41 '\"     is present, then a line break is forced before starting the sidebar.
  42 '\"
  43 '\" .VE
  44 '\"     End of vertical sidebar.
  45 '\"
  46 '\" .DS
  47 '\"     Begin an indented unfilled display.
  48 '\"
  49 '\" .DE
  50 '\"     End of indented unfilled display.
  51 '\"
  52 '\" .SO
  53 '\"     Start of list of standard options for a Tk widget.  The
  54 '\"     options follow on successive lines, in four columns separated
  55 '\"     by tabs.
  56 '\"
  57 '\" .SE
  58 '\"     End of list of standard options for a Tk widget.
  59 '\"
  60 '\" .OP cmdName dbName dbClass
  61 '\"     Start of description of a specific option.  cmdName gives the
  62 '\"     option's name as specified in the class command, dbName gives
  63 '\"     the option's name in the option database, and dbClass gives
  64 '\"     the option's class in the option database.
  65 '\"
  66 '\" .UL arg1 arg2
  67 '\"     Print arg1 underlined, then print arg2 normally.
  68 '\"
  69 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  70 '\"
  71 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  72 .if t .wh -1.3i ^B
  73 .nr ^l \n(.l
  74 .ad b
  75 '\"     # Start an argument description
  76 .de AP
  77 .ie !"\\$4"" .TP \\$4
  78 .el \{\
  79 .   ie !"\\$2"" .TP \\n()Cu
  80 .   el          .TP 15
  81 .\}
  82 .ta \\n()Au \\n()Bu
  83 .ie !"\\$3"" \{\
  84 \&\\$1  \\fI\\$2\\fP    (\\$3)
  85 .\".b
  86 .\}
  87 .el \{\
  88 .br
  89 .ie !"\\$2"" \{\
  90 \&\\$1  \\fI\\$2\\fP
  91 .\}
  92 .el \{\
  93 \&\\fI\\$1\\fP
  94 .\}
  95 .\}
  96 ..
  97 '\"     # define tabbing values for .AP
  98 .de AS
  99 .nr )A 10n
 100 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 101 .nr )B \\n()Au+15n
 102 .\"
 103 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 104 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 105 ..
 106 .AS Tcl_Interp Tcl_CreateInterp in/out
 107 '\"     # BS - start boxed text
 108 '\"     # ^y = starting y location
 109 '\"     # ^b = 1
 110 .de BS
 111 .br
 112 .mk ^y
 113 .nr ^b 1u
 114 .if n .nf
 115 .if n .ti 0
 116 .if n \l'\\n(.lu\(ul'
 117 .if n .fi
 118 ..
 119 '\"     # BE - end boxed text (draw box now)
 120 .de BE
 121 .nf
 122 .ti 0
 123 .mk ^t
 124 .ie n \l'\\n(^lu\(ul'
 125 .el \{\
 126 .\"     Draw four-sided box normally, but don't draw top of
 127 .\"     box if the box started on an earlier page.
 128 .ie !\\n(^b-1 \{\
 129 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 130 .\}
 131 .el \}\
 132 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 133 .\}
 134 .\}
 135 .fi
 136 .br
 137 .nr ^b 0
 138 ..
 139 '\"     # VS - start vertical sidebar
 140 '\"     # ^Y = starting y location
 141 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 142 .de VS
 143 .if !"\\$2"" .br
 144 .mk ^Y
 145 .ie n 'mc \s12\(br\s0
 146 .el .nr ^v 1u
 147 ..
 148 '\"     # VE - end of vertical sidebar
 149 .de VE
 150 .ie n 'mc
 151 .el \{\
 152 .ev 2
 153 .nf
 154 .ti 0
 155 .mk ^t
 156 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 157 .sp -1
 158 .fi
 159 .ev
 160 .\}
 161 .nr ^v 0
 162 ..
 163 '\"     # Special macro to handle page bottom:  finish off current
 164 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 165 '\"     # page bottom macro.
 166 .de ^B
 167 .ev 2
 168 'ti 0
 169 'nf
 170 .mk ^t
 171 .if \\n(^b \{\
 172 .\"     Draw three-sided box if this is the box's first page,
 173 .\"     draw two sides but no top otherwise.
 174 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 175 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 176 .\}
 177 .if \\n(^v \{\
 178 .nr ^x \\n(^tu+1v-\\n(^Yu
 179 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 180 .\}
 181 .bp
 182 'fi
 183 .ev
 184 .if \\n(^b \{\
 185 .mk ^y
 186 .nr ^b 2
 187 .\}
 188 .if \\n(^v \{\
 189 .mk ^Y
 190 .\}
 191 ..
 192 '\"     # DS - begin display
 193 .de DS
 194 .RS
 195 .nf
 196 .sp
 197 ..
 198 '\"     # DE - end display
 199 .de DE
 200 .fi
 201 .RE
 202 .sp
 203 ..
 204 '\"     # SO - start of list of standard options
 205 .de SO
 206 .SH "STANDARD OPTIONS"
 207 .LP
 208 .nf
 209 .ta 5.5c 11c
 210 .ft B
 211 ..
 212 '\"     # SE - end of list of standard options
 213 .de SE
 214 .fi
 215 .ft R
 216 .LP
 217 See the \\fBoptions\\fR manual entry for details on the standard options.
 218 ..
 219 '\"     # OP - start of full description for a single option
 220 .de OP
 221 .LP
 222 .nf
 223 .ta 4c
 224 Command-Line Name:      \\fB\\$1\\fR
 225 Database Name:  \\fB\\$2\\fR
 226 Database Class: \\fB\\$3\\fR
 227 .fi
 228 .IP
 229 ..
 230 '\"     # CS - begin code excerpt
 231 .de CS
 232 .RS
 233 .nf
 234 .ta .25i .5i .75i 1i
 235 ..
 236 '\"     # CE - end code excerpt
 237 .de CE
 238 .fi
 239 .RE
 240 ..
 241 .de UL
 242 \\$1\l'|0\(ul'\\$2
 243 ..
 244 .TH resource n 8.0 Tcl "Tcl Built-In Commands"
 245 .BS
 246 '\" Note:  do not modify the .SH NAME line immediately below!
 247 .SH NAME
 248 resource \- Manipulate Macintosh resources
 249 .SH SYNOPSIS
 250 \fBresource \fIoption\fR ?\fIarg arg ...\fR?
 251 .BE
 252
 253 .SH DESCRIPTION
 254 .PP
 255 The \fBresource\fR command provides some generic operations for
 256 dealing with Macintosh resources.  This command is only supported on
 257 the Macintosh platform.  Each Macintosh file consists of two
 258 \fIforks\fR: a \fIdata\fR fork and a \fIresource\fR fork.  You use the
 259 normal open, puts, close, etc. commands to manipulate the data fork.
 260 You must use this command, however, to interact with the resource
 261 fork.  \fIOption\fR indicates what resource command to perform.  Any
 262 unique abbreviation for \fIoption\fR is acceptable.  The valid options
 263 are:
 264 .TP
 265 \fBresource close \fIrsrcRef\fR
 266 Closes the given resource reference (obtained from \fBresource
 267 open\fR).  Resources from that resource file will no longer be
 268 available.
 269 .TP
 270 \fBresource delete\fR ?\fIoptions\fR? \fIresourceType\fR
 271 This command will delete the resource specified by \fIoptions\fR and
 272 type \fIresourceType\fR (see RESOURCE TYPES below).  The options
 273 give you several ways to specify the resource to be deleted.
 274 .RS
 275 .TP
 276 \fB\-id\fR \fIresourceId\fR
 277 If the \fB-id\fR option is given the id \fIresourceId\fR (see RESOURCE
 278 IDS below) is used to specify the resource to be deleted.  The id must
 279 be a number - to specify a name use the \fB\-name\fR option.
 280 .TP
 281 \fB\-name\fR \fIresourceName\fR
 282 If \fB-name\fR is specified, the resource named
 283 \fIresourceName\fR will be deleted.  If the \fB-id\fR is also
 284 provided, then there must be a resource with BOTH this name and
 285 this id.  If no name is provided, then the id will be used regardless
 286 of the name of the actual resource.
 287 .TP
 288 \fB\-file\fR \fIresourceRef\fR
 289 If the \fB-file\fR option is specified then the resource will be
 290 deleted from the file pointed to by \fIresourceRef\fR.  Otherwise the
 291 first resource with the given \fIresourceName\fR and or
 292 \fIresourceId\fR which is found on the resource file path will be
 293 deleted.  To inspect the file path, use the \fIresource files\fR command.
 294 .RE
 295 .TP
 296 \fBresource files ?\fIresourceRef\fR?
 297 If \fIresourceRef\fRis not provided, this command returns a Tcl list
 298 of the resource references for all the currently open resource files.
 299 The list is in the normal Macintosh search order for resources.  If
 300 \fIresourceRef\fR is specified, the command will
 301 return the path to the file whose resource fork is represented by that
 302 token.
 303 .TP
 304 \fBresource list \fIresourceType\fR ?\fIresourceRef\fR?
 305 List all of the resources ids of type \fIresourceType\fR (see RESOURCE
 306 TYPES below).  If \fIresourceRef\fR is specified then the command will
 307 limit the search to that particular resource file.  Otherwise, all
 308 resource files currently opened by the application will be searched.
 309 A Tcl list of either the resource name's or resource id's of the found
 310 resources will be returned.  See the RESOURCE IDS section below for
 311 more details about what a resource id is.
 312 .TP
 313 \fBresource open \fIfileName\fR ?\fIaccess\fR?
 314 Open the resource for the file \fIfileName\fR.  Standard file access
 315 permissions may also be specified (see the manual entry for \fBopen\fR
 316 for details).  A resource reference (\fIresourceRef\fR) is returned
 317 that can be used by the other resource commands.  An error can occur
 318 if the file doesn't exist or the file does not have a resource fork.
 319 However, if you open the file with write permissions the file and/or
 320 resource fork will be created instead of generating an error.
 321 .TP
 322 \fBresource read \fIresourceType\fR \fIresourceId\fR ?\fIresourceRef\fR?
 323 Read the entire resource of type \fIresourceType\fR (see RESOURCE
 324 TYPES below) and the name or id of \fIresourceId\fR (see RESOURCE IDS
 325 below) into memory and return the result.  If \fIresourceRef\fR is
 326 specified we limit our search to that resource file, otherwise we
 327 search all open resource forks in the application.  It is important to
 328 note that most Macintosh resource use a binary format and the data
 329 returned from this command may have embedded NULLs or other non-ASCII
 330 data.
 331 .TP
 332 \fBresource types ?\fIresourceRef\fR?
 333 This command returns a Tcl list of all resource types (see RESOURCE
 334 TYPES below) found in the resource file pointed to by
 335 \fIresourceRef\fR.  If \fIresourceRef\fR is not specified it will
 336 return all the resource types found in every resource file currently
 337 opened by the application.
 338 .TP
 339 \fBresource write\fR ?\fIoptions\fR? \fIresourceType\fR \fIdata\fR
 340 This command will write the passed in \fIdata\fR as a new resource of
 341 type \fIresourceType\fR (see RESOURCE TYPES below).  Several options
 342 are available that describe where and how the resource is stored.
 343 .RS
 344 .TP
 345 \fB\-id\fR \fIresourceId\fR
 346 If the \fB-id\fR option is given the id \fIresourceId\fR (see RESOURCE
 347 IDS below) is used for the new resource, otherwise a unique id will be
 348 generated that will not conflict with any existing resource.  However,
 349 the id must be a number - to specify a name use the \fB\-name\fR option.
 350 .TP
 351 \fB\-name\fR \fIresourceName\fR
 352 If \fB-name\fR is specified the resource will be named
 353 \fIresourceName\fR, otherwise it will have the empty string as the
 354 name.
 355 .TP
 356 \fB\-file\fR \fIresourceRef\fR
 357 If the \fB-file\fR option is specified then the resource will be
 358 written in the file pointed to by \fIresourceRef\fR, otherwise the
 359 most recently open resource will be used.
 360 .TP
 361 \fB\-force\fR
 362 If the target resource already exists, then by default Tcl will not
 363 overwrite it, but raise an error instead.  Use the -force flag to
 364 force overwriting the extant resource.
 365 .RE
 366
 367 .SH "RESOURCE TYPES"
 368 Resource types are defined as a four character string that is then
 369 mapped to an underlying id.  For example, \fBTEXT\fR refers to the
 370 Macintosh resource type for text.  The type \fBSTR#\fR is a list of
 371 counted strings.  All Macintosh resources must be of some type.  See
 372 Macintosh documentation for a more complete list of resource types
 373 that are commonly used.
 374
 375 .SH "RESOURCE IDS"
 376 For this command the notion of a resource id actually refers to two
 377 ideas in Macintosh resources.  Every place you can use a resource Id
 378 you can use either the resource name or a resource number.  Names are
 379 always searched or returned in preference to numbers.  For example,
 380 the \fBresource list\fR command will return names if they exist or
 381 numbers if the name is NULL.
 382
 383 .SH "PORTABILITY ISSUES"
 384 The resource command is only available on Macintosh.
 385
 386 .SH "SEE ALSO"
 387 open(n)
 388
 389 .SH KEYWORDS
 390 open, resource