diff options
Diffstat (limited to 'funtools/man/man3/funref.3')
| -rw-r--r-- | funtools/man/man3/funref.3 | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/funtools/man/man3/funref.3 b/funtools/man/man3/funref.3 deleted file mode 100644 index 7c6156a..0000000 --- a/funtools/man/man3/funref.3 +++ /dev/null @@ -1,287 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funref 3" -.TH funref 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunRef \- the Funtools Reference Handle -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -A description of how to use a Funtools reference handle to connect a -Funtools input file to an output file. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The Funtools reference handle connects a Funtools input file to a -Funtools output file so that parameters (or even whole extensions) can -be copied from the one to the other. To make the connection, the Funtools -handle of the input file is passed to the -final argument of the -\&\fIFunOpen()\fR call for the output file: -.PP -.Vb 4 -\& if( !(ifun = FunOpen(argv[1], "r", NULL)) ) -\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); -\& if( !(ofun = FunOpen(argv[2], "w", ifun)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); -.Ve -.PP -It does not matter what type of input or output file (or extension) is -opened, or whether they are the same type. When the output image or -binary table is written using -\&\fIFunImagePut()\fR -or -\&\fIFunTableRowPut()\fR -an appropriate header will be written first, with parameters copied -from the input extension. Of course, invalid parameters will be -removed first, e.g., if the input is a binary table and the output is -an image, then binary table parameters such as \s-1TFORM\s0, \s-1TUNIT\s0, -etc. parameters will not be copied to the output. -.PP -Use of a reference handle also allows default values to be passed -to -\&\fIFunImagePut()\fR in order to -write out an output image with the same dimensions and data type -as the input image. To use the defaults from the input, a value -of 0 is entered for dim1, dim2, and bitpix. For example: -.PP -.Vb 5 -\& fun = FunOpen(argv[1], "r", NULL); -\& fun2 = FunOpen(argv[2], "w", fun); -\& buf = FunImageGet(fun, NULL, NULL); -\& ... process image data ... -\& FunImagePut(fun2, buf, 0, 0, 0, NULL); -.Ve -.PP -Of course, you often want to get information about the data type -and dimensions of the image for processing. The above code -is equivalent to the following: -.PP -.Vb 7 -\& fun = FunOpen(argv[1], "r", NULL); -\& fun2 = FunOpen(argv[2], "w", fun); -\& buf = FunImageGet(fun, NULL, NULL); -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, -\& FUN_SECT_BITPIX, &bitpix, 0); -\& ... process image data ... -\& FunImagePut(fun2, buf, dim1, dim2, bitpix, NULL); -.Ve -.PP -It is possible to change the reference handle for a given output Funtools -handle using the -\&\fIFunInfoPut()\fR routine: -.PP -.Vb 2 -\& /* make the new extension the reference handle for the output file */ -\& FunInfoPut(fun2, FUN_IFUN, &fun, 0); -.Ve -.PP -When this is done, Funtools specially resets the output file to start -a new output extension, which is connected to the new input reference -handle. You can use this mechanism to process multiple input extensions -into a single output file, by successively opening the former and -setting the reference handle for the latter. For example: -.PP -.Vb 18 -\& /* open a new output FITS file */ -\& if( !(fun2 = FunOpen(argv[2], "w", NULL)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); -\& /* process each input extension in turn */ -\& for(ext=0; ;ext++){ -\& /* get new extension name */ -\& sprintf(tbuf, "%s[%d]", argv[1], ext); -\& /* open it -- if we cannot open it, we are done */ -\& if( !(fun=FunOpen(tbuf, "r", NULL)) ) -\& break; -\& /* make the new extension the reference handle for the output file */ -\& FunInfoPut(fun2, FUN_IFUN, &fun, 0); -\& ... process ... -\& /* flush output extension (write padding, etc.) */ -\& FunFlush(fun2, NULL); -\& /* close the input extension */ -\& FunClose(fun); -\& } -.Ve -.PP -In this example, the output file is opened first. Then each successive -input extension is opened, and the output reference handle is set to -the newly opened input handle. After data processing is performed, the -output extension is flushed and the input extension is closed, in -preparation for the next input extension. -.PP -Finally, a reference handle can be used to copy other extensions from -the input file to the output file. Copy of other extensions is -controlled by adding a \*(L"C\*(R" or \*(L"c\*(R" to the mode string of the -\&\fIFunOpen()\fR -call \fBof the input reference file\fR. If \*(L"C\*(R" is specified, then -other extensions are \fBalways\fR copied (i.e., copy is forced by the -application). If \*(L"c\*(R" is used, then other extensions are copied if the -user requests copying by adding a plus sign \*(L"+\*(R" to the extension name -in the bracket specification. For example, the \fBfuntable\fR -program utilizes user-specified \*(L"c\*(R" mode so that the second example -below will copy all extensions: -.PP -.Vb 4 -\& # copy only the EVENTS extension -\& csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev -\& # copy ALL extensions -\& csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev -.Ve -.PP -When extension copy is specified in the input file, the call to -\&\fIFunOpen()\fR -on the input file delays the actual file open until the output file -also is opened (or until I/O is performed on the input file, which -ever happens first). Then, when the output file is opened, the input -file is also opened and input extensions are copied to the output -file, up to the specific extension being opened. Processing of input -and output extensions then proceed. -.PP -When extension processing is complete, the remaining extensions need to -be copied from input to output. This can be done explicitly, using the -\&\fIFunFlush()\fR -call with the \*(L"copy=remaining\*(R" plist: -.PP -.Vb 1 -\& FunFlush(fun, "copy=remaining"); -.Ve -.PP -Alternatively, this will happen automatically, if the output file -is closed \fBbefore\fR the input file: -.PP -.Vb 5 -\& /* we could explicitly flush remaining extensions that need copying */ -\& /* FunFlush(fun2, "copy=remaining"); */ -\& /* but if we close output before input, end flush is done automatically */ -\& FunClose(fun2); -\& FunClose(fun); -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages |