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 infor-
       mation 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 appli-
            cations.

       +------------------+----------------------------------------+
       |    argument      |                purpose                 |
       |LFS_CFLAGS        | obtain  compilation flags necessary to |
       |                  | enable  the  large  file   compilation |
       |                  | environment                            |
       |LFS_LDFLAGS       | obtain link editor options             |
       |LFS_LIBS          | obtain link library names              |
       |LFS_LINTFLAGS     | obtain 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  compila-
            tion 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 <procfs.h>.

         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 <libelf.h> or <sys/procfs.h> 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-compiled 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 compi-
       lation 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 interfaces, not with _FILE_OFFSET_BITS set to 64.  This deficiency  hampers
       static error-checking for programs compiled in the large file compilation environment.

       Symbolic  formats analogous to those found in <sys/int_fmtio.h> 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)