unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

lfcompile(5)          Standards, Environments, and Macros         lfcompile(5)



NAME
       lfcompile - large file compilation environment for 32-bit applications

DESCRIPTION
       All  64-bit  applications  can  manipulate  large files by default. The
       methods described on this page allow 32-bit applications to  manipulate
       large files.

       In  the large file compilation environment, source interfaces are bound
       to appropriate 64-bit functions, structures, and types.   Compiling  in
       this  environment allows 32-bit applications to access files whose size
       is greater than or equal to 2 Gbyte ( 2**31 bytes).

       Each interface named xxx() that needs  to  access  64-bit  entities  to
       access  large files maps to a xxx64() call in the resulting binary. All
       relevant data types are defined to be of  correct  size  (for  example,
       off_t has a typedef definition for a 64-bit entity).

       An  application  compiled  in this environment is able to use the xxx()
       source interfaces to access both large and  small  files,  rather  than
       having  to  explicitly utilize the transitional xxx64() interface calls
       to access large files. See the lfcompile64(5) manual page for  informa-
       tion regarding the transitional compilation environment.

       Applications  can be compiled in the large file compilation environment
       by using the following methods:

         o  Use the getconf(1) utility with  one  or  more  of  the  arguments
            listed in the table below. This method is recommended for portable
            applications.



       tab() box; cw(1.680556i)| cw(3.819444i)  lw(1.680556i)|  lw(3.819444i).
       argumentpurpose  LFS_CFLAGST{  obtain  compilation  flags  necessary to
       enable the large file compilation environment T} LFS_LDFLAGSobtain link
       editor  options  LFS_LIBSobtain  link library names LFS_LINTFLAGSobtain
       lint options


         o  Set the compile-time flag _FILE_OFFSET_BITS to 64 before including
            any  headers.  Applications  may  combine  objects produced in the
            large file compilation environment with objects  produced  in  the
            transitional  compilation  environment,  but  must be careful with
            respect to interoperability between  those  objects.  Applications
            should  not  declare  global variables of types whose sizes change
            between  compilation environments.


   Access to Additional Large File Interfaces
       The fseek() and  ftell()  functions  do  not  map  to  functions  named
       fseek64()  and ftell64(); rather, the large file additions fseeko() and
       ftello(), have functionality identical to fseek() and  ftell()  and  do
       map  to  the  64-bit  functions fseeko64() and ftello64(). Applications
       wishing to access large files should use fseeko() and ftello() in place
       of  fseek()  and  ftell(). See the fseek(3C) and ftell(3C) manual pages
       for information about  fseeko() and ftello().

       Applications wishing to access  fseeko() and ftello() as  well  as  the
       POSIX  and X/Open specification-conforming interfaces should define the
       macro _LARGEFILE_SOURCE to be 1 and set whichever feature  test  macros
       are appropriate to obtain the desired environment (see standards(5)).

EXAMPLES
       In  the  following  examples, the large file compilation environment is
       accessed by invoking the getconf utility  with  one  of  the  arguments
       listed  in  the  table  above. The additional large file interfaces are
       accessed by specifying -D_LARGEFILE_SOURCE.

       The examples that use the form of command substitution  specifying  the
       command  within  parentheses  preceded by a dollar sign can be executed
       only in a POSIX-conforming shell such as the Korn Shell  (see  ksh(1)).
       In  a shell that is not POSIX-conforming, such as the Bourne Shell (see
       sh(1)) and the C Shell (see csh(1)), the getconf calls must be enclosed
       within grave accent marks, as shown in the second example.

       Example 1: An example of compiling a program with a "large"  off_t, and
       that uses fseeko(), ftello(), and yacc(1)

       $ c89 -D_LARGEFILE_SOURCE                \
             -D_FILE_OFFSET_BITS=64 -o foo      \
             $(getconf LFS_CFLAGS) y.tab.c b.o  \
             $(getconf LFS_LDFLAGS)             \
             -ly $(getconf LFS_LIBS)


       Example 2: An example of compiling a program with a "large" off_t  that
       does  not  use  fseeko()  and  ftello() and has no application specific
       libraries:

       % c89 -D_FILE_OFFSET_BITS=64     \
             `getconf LFS_CFLAGS` a.c   \
             `getconf LFS_LDFLAGS`      \
             `getconf LFS_LIBS`         \


       Example 3: An example of compiling a program with  a  "default"   off_t
       and that uses fseeko() and ftello():

       $ c89 -D_LARGEFILE_SOURCE  a.c


SEE ALSO
       csh(1),  getconf(1),  ksh(1),  lint(1B),  sh(1),  fseek(3C), ftell(3C),
       lf64(5), lfcompile64(5), standards(5)

NOTES
       Certain system-specific or non-portable interfaces are  not  usable  in
       the large file compilation environment.  Known cases are:

         o  Kernel data structures read from /dev/kmem.

         o  Interfaces in the kernel virtual memory library, -lkvm.

         o  Interfaces in the ELF access library, -lelf.

         o  Interfaces to /proc defined in <&lt;procfs.h>&gt;.

         o  The ustat(2) system call.


       Programs  that use these interfaces should not be compiled in the large
       file compilation environment.  As a partial  safeguard  against  making
       this  mistake,  including  either  of  the <&lt;libelf.h>&gt; or <&lt;sys/procfs.h>&gt;
       header files will induce a compilation error when the large file compi-
       lation environment is enabled.

       In  general, caution should be exercised when using any separately-com-
       piled library whose interfaces include data items of type off_t or  the
       other  redefined  types  either  directly  or  indirectly, such as with
       'struct stat'. (The redefined types are off_t, rlim_t, ino_t, blkcnt_t,
       fsblkcnt_t, and fsfilcnt_t.) For the large file compilation environment
       to work correctly with such a  library,  the  library  interfaces  must
       include  the appropriate xxx64() binary entry points and must have them
       mapped to the corresponding primary functions when _FILE_OFFSET_BITS is
       set to 64.

       Care  should be exercised using any of the printf() or scanf() routines
       on variables of the types mentioned above.  In the large file  compila-
       tion  environment,  these  variables should be printed or scanned using
       long long formats.

BUGS
       The  lint(1B)  utility  will  generate  spurious  error  messages  when
       _FILE_OFFSET_BITS  is  set to 64.  This is because the binary libc lint
       library, /usr/lib/llib-lc.ln, is compiled only for the standard  inter-
       faces,  not  with _FILE_OFFSET_BITS set to 64.  This deficiency hampers
       static error-checking for programs compiled in the large file  compila-
       tion environment.

       Symbolic  formats  analogous to those found in <&lt;sys/int_fmtio.h>&gt; do not
       exist for printing or scanning variables of the types  that  are  rede-
       fined in the large file compilation environment.



SunOS 5.10                        23 Jul 2001                     lfcompile(5)