src/tiff/man/TIFFSetField.3tiff

   1 .\"
   2 .\" Copyright (c) 1988-1997 Sam Leffler
   3 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
   4 .\"
   5 .\" Permission to use, copy, modify, distribute, and sell this software and
   6 .\" its documentation for any purpose is hereby granted without fee, provided
   7 .\" that (i) the above copyright notices and this permission notice appear in
   8 .\" all copies of the software and related documentation, and (ii) the names of
   9 .\" Sam Leffler and Silicon Graphics may not be used in any advertising or
  10 .\" publicity relating to the software without the specific, prior written
  11 .\" permission of Sam Leffler and Silicon Graphics.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
  14 .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  15 .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  16 .\"
  17 .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
  18 .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
  19 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  20 .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  21 .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  22 .\" OF THIS SOFTWARE.
  23 .\"
  24 .if n .po 0
  25 .TH TIFFSetField 3TIFF "October 29, 2004" "libtiff"
  26 .SH NAME
  27 TIFFSetField, TIFFVSetField \- set the value(s) of a tag in a
  28 .SM TIFF
  29 file open for writing
  30 .SH SYNOPSIS
  31 .B "#include <tiffio.h>"
  32 .sp
  33 .BI "int TIFFSetField(TIFF *" tif ", ttag_t " tag ", " ... ")"
  34 .sp
  35 .B "#include <stdarg.h>"
  36 .sp
  37 .BI "int TIFFVSetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
  38 .SH DESCRIPTION
  39 .IR TIFFSetField
  40 sets the value of a field
  41 or pseudo-tag in the current directory associated with
  42 the open
  43 .SM TIFF
  44 file
  45 .IR tif .
  46 (A
  47 .I pseudo-tag
  48 is a parameter that is used to control the operation of the
  49 .SM TIFF
  50 library but whose value is not read or written to the underlying file.)
  51 To set the value of a field
  52 the file must have been previously opened for writing with
  53 .IR TIFFOpen (3TIFF);
  54 pseudo-tags can be set whether the file was opened for reading
  55 or writing.
  56 The field is identified by
  57 .IR tag ,
  58 one of the values defined in the include file
  59 .B tiff.h
  60 (see also the table below).
  61 The actual value is specified using a variable argument list,
  62 as prescribed by the
  63 .IR stdarg (3)
  64 interface (\c
  65 or, on some machines, the
  66 .IR varargs (3)
  67 interface.)
  68 .PP
  69 .IR TIFFVSetField
  70 is functionally equivalent to
  71 .IR TIFFSetField
  72 except that it takes a pointer to a variable
  73 argument list.
  74 .I TIFFVSetField
  75 is useful for writing routines that are layered
  76 on top of the functionality provided by
  77 .IR TIFFSetField .
  78 .PP
  79 The tags understood by
  80 .IR libtiff ,
  81 the number of parameter values, and the
  82 expected types for the parameter values are shown below.
  83 The data types are:
  84 .I char*
  85 is null-terminated string and corresponds to the
  86 .SM ASCII
  87 data type;
  88 .I uint16
  89 is an unsigned 16-bit value;
  90 .I uint32
  91 is an unsigned 32-bit value;
  92 .I uint16*
  93 is an array of unsigned 16-bit values.
  94 .I void*
  95 is an array of data values of unspecified type.
  96
  97 Consult the
  98 .SM TIFF
  99 specification for information on the meaning of each tag.
 100 .PP
 101 .nf
 102 .ta \w'TIFFTAG_CONSECUTIVEBADFAXLINES'u+2n +\w'Count'u+2n +\w'TIFFFaxFillFunc \(dg'u+2n
 103 \fITag Name\fP  \fICount\fP     \fITypes\fP     \fINotes\fP
 104 .sp 5p
 105 TIFFTAG_ARTIST  1       char*
 106 TIFFTAG_BADFAXLINES     1       uint32
 107 TIFFTAG_BITSPERSAMPLE   1       uint16  \(dg
 108 TIFFTAG_CLEANFAXDATA    1       uint16
 109 TIFFTAG_COLORMAP        3       uint16* 1<<BitsPerSample arrays
 110 TIFFTAG_COMPRESSION     1       uint16  \(dg
 111 TIFFTAG_CONSECUTIVEBADFAXLINES  1       uint32
 112 TIFFTAG_COPYRIGHT       1       char*
 113 TIFFTAG_DATETIME        1       char*
 114 TIFFTAG_DOCUMENTNAME    1       char*
 115 TIFFTAG_DOTRANGE        2       uint16
 116 TIFFTAG_EXTRASAMPLES    2       uint16,uint16*  \(dg count & types array
 117 TIFFTAG_FAXFILLFUNC     1       TIFFFaxFillFunc G3/G4 compression pseudo-tag
 118 TIFFTAG_FAXMODE 1       int     \(dg G3/G4 compression pseudo-tag
 119 TIFFTAG_FILLORDER       1       uint16  \(dg
 120 TIFFTAG_GROUP3OPTIONS   1       uint32  \(dg
 121 TIFFTAG_GROUP4OPTIONS   1       uint32  \(dg
 122 TIFFTAG_HALFTONEHINTS   2       uint16
 123 TIFFTAG_HOSTCOMPUTER    1       char*
 124 TIFFTAG_ICCPROFILE      2       uint32,void*    count, profile data
 125 TIFFTAG_IMAGEDEPTH      1       uint32  \(dg
 126 TIFFTAG_IMAGEDESCRIPTION        1       char*
 127 TIFFTAG_IMAGELENGTH     1       uint32
 128 TIFFTAG_IMAGEWIDTH      1       uint32  \(dg
 129 TIFFTAG_INKNAMES        2       uint16, char*
 130 TIFFTAG_INKSET  1       uint16  \(dg
 131 TIFFTAG_JPEGCOLORMODE   1       int     \(dg JPEG pseudo-tag
 132 TIFFTAG_JPEGQUALITY     1       int     JPEG pseudo-tag
 133 TIFFTAG_JPEGTABLES      2       uint32*,void*   \(dg count & tables
 134 TIFFTAG_JPEGTABLESMODE  1       int     \(dg JPEG pseudo-tag
 135 TIFFTAG_MAKE    1       char*
 136 TIFFTAG_MATTEING        1       uint16  \(dg
 137 TIFFTAG_MAXSAMPLEVALUE  1       uint16
 138 TIFFTAG_MINSAMPLEVALUE  1       uint16
 139 TIFFTAG_MODEL   1       char*
 140 TIFFTAG_ORIENTATION     1       uint16
 141 TIFFTAG_PAGENAME        1       char*
 142 TIFFTAG_PAGENUMBER      2       uint16
 143 TIFFTAG_PHOTOMETRIC     1       uint16
 144 TIFFTAG_PHOTOSHOP       ?       uint32,void*    count, data
 145 TIFFTAG_PLANARCONFIG    1       uint16  \(dg
 146 TIFFTAG_PREDICTOR       1       uint16  \(dg
 147 TIFFTAG_PRIMARYCHROMATICITIES   1       float*  6-entry array
 148 TIFFTAG_REFERENCEBLACKWHITE     1       float*  \(dg 6-entry array
 149 TIFFTAG_RESOLUTIONUNIT  1       uint16
 150 TIFFTAG_RICHTIFFIPTC    2       uint32,void*    count, data
 151 TIFFTAG_ROWSPERSTRIP    1       uint32  \(dg must be > 0
 152 TIFFTAG_SAMPLEFORMAT    1       uint16  \(dg
 153 TIFFTAG_SAMPLESPERPIXEL 1       uint16  \(dg value must be <= 4
 154 TIFFTAG_SMAXSAMPLEVALUE 1       double
 155 TIFFTAG_SMINSAMPLEVALUE 1       double
 156 TIFFTAG_SOFTWARE        1       char*
 157 TIFFTAG_STONITS 1       double  \(dg
 158 TIFFTAG_SUBFILETYPE     1       uint32
 159 TIFFTAG_SUBIFD  2       uint16,uint32*  count & offsets array
 160 TIFFTAG_TARGETPRINTER   1       char*
 161 TIFFTAG_THRESHHOLDING   1       uint16
 162 TIFFTAG_TILEDEPTH       1       uint32  \(dg
 163 TIFFTAG_TILELENGTH      1       uint32  \(dg must be a multiple of 8
 164 TIFFTAG_TILEWIDTH       1       uint32  \(dg must be a multiple of 8
 165 TIFFTAG_TRANSFERFUNCTION        1 or 3\(dd uint16*      1<<BitsPerSample entry arrays
 166 TIFFTAG_WHITEPOINT      1       float*  2-entry array
 167 TIFFTAG_XMLPACKET       2       uint32,void*    count, data
 168 TIFFTAG_XPOSITION       1       float
 169 TIFFTAG_XRESOLUTION     1       float
 170 TIFFTAG_YCBCRCOEFFICIENTS       1       float*  \(dg 3-entry array
 171 TIFFTAG_YCBCRPOSITIONING        1       uint16  \(dg
 172 TIFFTAG_YCBCRSAMPLING   2       uint16  \(dg
 173 TIFFTAG_YPOSITION       1       float
 174 TIFFTAG_YRESOLUTION     1       float
 175 .fi
 176 .sp 5p
 177 \(dg Tag may not have its values changed once data is written.
 178 .br
 179 .fi
 180 \(dd
 181 If
 182 .I SamplesPerPixel
 183 is one, then a single array is passed; otherwise three arrays should be
 184 passed.
 185 .fi
 186 * The contents of this field are quite complex.  See
 187 .BR "The ICC Profile Format Specification" ,
 188 Annex B.3 "Embedding ICC Profiles in TIFF Files"
 189 (available at http://www.color.org) for an explanation.
 190 .br
 191 .SH "RETURN VALUES"
 192 1 is returned if the operation was successful.
 193 Otherwise, 0 is returned if an error was detected.
 194 .SH DIAGNOSTICS
 195 All error messages are directed to the
 196 .BR TIFFError (3TIFF)
 197 routine.
 198 .PP
 199 \fB%s: Cannot modify tag "%s" while writing\fP.
 200 Data has already been written to the file, so the
 201 specified tag's value can not be changed.
 202 This restriction is applied to all tags that affect
 203 the format of written data.
 204 .PP
 205 \fB%d: Bad value for "%s"\fP.
 206 An invalid value was supplied for the named tag.
 207 .SH "SEE ALSO"
 208 .BR TIFFOpen (3TIFF),
 209 .BR TIFFGetField (3TIFF),
 210 .BR TIFFSetDirectory (3TIFF),
 211 .BR TIFFWriteDirectory (3TIFF),
 212 .BR TIFFReadDirectory (3TIFF),
 213 .BR libtiff (3TIFF)
 214 .PP
 215 Libtiff library home page:
 216 .BR http://www.remotesensing.org/libtiff/