src/tiff/man/TIFFSetField.3tiff

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