Chapter Contents

Previous

Next
fattr

fattr



Return File Attribute Information

Portability: SAS/C extension


SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLE
RELATED FUNCTIONS
SEE ALSO


SYNOPSIS

#include <lcio.h>

const struct fattrib *fattr(FILE *f);


DESCRIPTION

The fattr function returns a pointer to a structure containing information about the attributes of the stream associated with the FILE object addressed by the f argument. The return value is a pointer to a fattrib structure as defined in <lcio.h> . Note that the returned pointer is a const pointer, so you can inspect the structure fields but not modify them.

The fattrib structure is defined as

struct fattrib {
      unsigned long props;        /* file properties           */
      unsigned short abilities;   /* how file can be used      */
      unsigned short reclen;      /* maximum record length     */
                                  /* (0 if no limit)           */
      unsigned short blksize;     /* block size or VSAM        */
                                  /* control interval size     */
                                  /* (0 if not meaningful)     */
      unsigned short keylen;      /* key length or 0           */
      unsigned short keyoff;      /* record offset of key or 0 */
      char am[5];                 /* name of access method     */
      char _1[1];                 /* reserved                  */
      long _2[10];                /* reserved                  */
   } ;

The props field of the fattrib structure is a bit string composed of bits specifying whether the file has a number of specific properties. The abilities field is a bit string specifying whether the file supports specific file operations. Note that not all bits of these fields are defined and that undefined bits do not have to be set to 0.

The bit definitions for the props field are
_Fappend indicates that the stream was opened for append.
_Fcommit indicates that commit=yes was specified or defaulted.
_Fdupkey indicates that the file permits records with duplicate keys.
_Ffixed indicates that all records have the same size.
_Fgeneric indicates that the file supports generic key searches.
_Finexact indicates that the file supports inexact searches.
_Fkeyed indicates a stream opened for keyed access.
_Fphyskey indicates that file keys are physically recorded. This is set for a KSDS but not an ESDS or RRDS.
_Fprintform indicates that the file has print format (has RECFM A or is a CMS LISTING file).
_Fprint indicates that print=yes is in effect for the file.
_Fprocess indicates that a hierarchical file system (HFS) file associated with the current process is accessible in any child process created by fork or exec , unless fcntl has prevented access.
_Frelative indicates that file positions are expressed as relative-byte offsets.
_Fshared indicates that an HFS file can be shared with another process. Some library optimizations of seek operations are disabled.
_Fspanbuf indicates that records may be longer than the buffer size.
_Fspanrec indicates that a single record can be written in more than one physical block.
_Fstream indicates that record boundaries are ignored.
_Fterm indicates a terminal file.
_Ftext indicates a text stream.
_Ftrunc indicates that trunc=yes was specified or defaulted.

The bit definitions for the abilities field are
_Fcan_delete indicates that the file supports deletion of records with kdelete .
_Fcan_grow indicates that new records can be added to the file.
_Fcan_read indicates that the stream can be read.
_Fcan_rewind indicates that the stream supports seeking to the start of file.
_Fcan_setbuf Indicates that an HFS file or socket supports setbuf or setvbuf to define an I/O buffer. setbuf and setvbuf can only be the first file operation. _Fcan_setbuf remains in effect while a file is open.
_Fcan_search indicates that the file supports key searches with ksearch .
_Fcan_seek indicates that the stream supports positioning with fsetpos .
_Fcan_skend indicates that the stream supports seeking to the end of file.
_Fcan_tell indicates that the file supports position inquiries by fgetpos or kgetpos .
_Fcan_write indicates that the stream can be written.

The reclen field of the fattrib structure includes space for the key in a keyed file. Thus, for an ESDS or RRDS opened for keyed access, the returned reclen value is 4 bytes greater than the maximum physical record size. In all cases in which a non-zero value is returned for reclen= , the value returned is the same as would be specified by the reclen= amparm; that is, the value is the same as the amount of storage required to read the largest possible record in the file.


RETURN VALUE

The fattr function returns a pointer to an attrib structure for the file. If the argument to fattr addresses a closed file object, a pointer to a dummy fattrib structure is returned with the abilities field equal to 0. If the argument to fattr is an invalid FILE pointer, the results are unpredictable.


EXAMPLE

#include <lcio.h>
#include <stdio.h>

main()
{
  FILE *outfile;

  outfile = afopen("tso:userid.test", "w", "",
                   "recfm=v, reclen=132");

  if (fattr(outfile)->props & _Fprintform)
     putc('\f', outfile);

  fclose(outfile);
}


RELATED FUNCTIONS

cmsstat , fstat , osddinfo , osdsinfo , stat


SEE ALSO


Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.