cups/api-filedir.shtml

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