cups/api-filedir.shtml

   1 <!--
   2   "$Id: api-filedir.shtml 177 2006-06-21 00:20:03Z jlovell $"
   3
   4   File and directory API introduction for the Common UNIX Printing System (CUPS).
   5
   6   Copyright 1997-2005 by Easy Software Products.
   7
   8   These coded instructions, statements, and computer programs are the
   9   property of Easy Software Products and are protected by Federal
  10   copyright law.  Distribution and use rights are outlined in the file
  11   "LICENSE.txt" which should have been included with this file.  If this
  12   file is missing or damaged please contact Easy Software Products
  13   at:
  14
  15       Attn: CUPS Licensing Information
  16       Easy Software Products
  17       44141 Airport View Drive, Suite 204
  18       Hollywood, Maryland 20636 USA
  19
  20       Voice: (301) 373-9600
  21       EMail: cups-info@cups.org
  22         WWW: http://www.cups.org
  23 -->
  24
  25 <h2 class='title'>Introduction</h2>
  26
  27 <p>The CUPS file and directory APIs provide portable interfaces
  28 for manipulating files and listing files and directories. Unlike
  29 stdio <tt>FILE</tt> streams, the <tt>cupsFile</tt> functions
  30 allow you to open more than 256 files at any given time. They
  31 also manage the platform-specific details of locking, large file
  32 support, line endings (CR, LF, or CR LF), and reading and writing
  33 files using Flate ("gzip") compression. Finally, you can also
  34 connect, read from, and write to network connections using the
  35 <tt>cupsFile</tt> functions.</p>
  36
  37 <p>The <tt>cupsDir</tt> functions manage the platform-specific
  38 details of directory access/listing and provide a convenient way
  39 to get both a list of files and the information (permissions,
  40 size, timestamp, etc.) for each of those files.</p>
  41
  42 <p>The CUPS scheduler (<tt>cupsd</tt>), <tt>mailto</tt> notifier,
  43 and many of the CUPS API functions use these functions for
  44 everything except console (stdin, stdout, stderr) I/O.</p>
  45
  46 <h2 class='title'>General Usage</h2>
  47
  48 <p>The <var>&lt;cups/dir.h&gt;</var> and
  49 <var>&lt;cups/file.h&gt;</var> header files must be included to
  50 use the <tt>cupsDir</tt> and <tt>cupsFile</tt> functions,
  51 respectively.</p>
  52
  53 <p>Programs using these functions must be linked to the CUPS
  54 library: <var>libcups.a</var>, <var>libcups.so.2</var>,
  55 <var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
  56 <var>libcups2.lib</var> depending on the platform. The following
  57 command compiles <var>myprogram.c</var> using GCC and the CUPS
  58 library:</p>
  59
  60 <pre class='command'>
  61 <kbd>gcc -o myprogram myprogram.c -lcups</kbd>
  62 </pre>
  63
  64 <h2 class='title'>Compatibility</h2>
  65
  66 <p>All of these functions require CUPS 1.2 or higher.</p>