SAS/C Library Reference, Vol. 1

fattr -- Return File Attribute Information

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 VALUES

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