Provided by: libncarg-dev_6.6.2-10build2_amd64 bug

NAME

       CGM_open,  CGM_close,  CGM_lseek,  CGM_read,  CGM_write, CGM_directory, CGM_freeDirectory,
       CGM_printDirectory, CGM_getInstr, CGM_flushGetInstr,  CGM_putInstr,  CGM_flushOutputInstr,
       CGM_initMetaEdit,   CGM_termMetaEdit,  CGM_copyFrames,  CGM_deleteFrames,  CGM_mergeFrames
       CGM_moveFrames,     CGM_readFrames,     CGM_valid,     CGM_writeFile,     CGM_writeFrames,
       CGM_appendFrames - Computer Graphics Metafile operations

SYNTAX

       #include <cgm_tools.h>

       Cgm_fd CGM_open(metafile, size, flags, mode)
       char *metafile;
       unsigned size;
       int flags;
       int mode;

       int CGM_close(cgm_fd)
       Cgm_fd cgm_fd;

       int CGM_lseek(cgm_fd, offset)
       Cgm_fd cgm_fd;
       int offset;

       int CGM_read(cgm_fd, buf)
       Cgm_fd cgm_fd;
       unsigned char *buf;

       int CGM_write(cgm_fd, buf)
       Cgm_fd cgm_fd;
       unsigned char *buf;

       Directory *CGM_directory(cgm_fd)
       Cgm_fd cgm_fd;

       void CGM_freeDirectory(dir)
       Directory *dir;

       void CGM_printDirectory(dir)
       Directory *dir;

       int CGM_getInstr(cgm_fd, instr)
       Cgm_fd cgm_fd;
       Instr *instr;

       void CGM_flushGetInstr(cgm_fd)
       Cgm_fd cgm_fd;

       int CGM_putInstr(cgm_fd, instr)
       Cgm_fd cgm_fd;
       Instr *instr;

       int CGM_flushOutputInstr(cgm_fd)
       Cgm_fd cgm_fd;

       Directory *CGM_initMetaEdit (metafile, size)
       char *metafile;
       unsigned int size;

       int CGM_termMetaEdit()

       Directory *CGM_copyFrames(start, num, target )
       unsigned int start;
       int num;
       unsigned int target;

       Directory *CGM_deleteFrames(start, num)
       unsigned int start,
       num;

       Directory *CGM_mergeFrames(bottom, top)
       unsigned bottom, top;

       Directory *CGM_moveFrames (start, num, target)
       unsigned int start, num, target;

       Directory *CGM_readFrames(metafile, start, num, target, size)
       char *metafile;
       unsigned int start;
       int num;
       unsigned int target, size;

       int *CGM_validCGM(metafile)
       char *metafile;

       int CGM_writeFile(metafile)
       char *metafile;

       int CGM_writeFrames(metafile, start, num)
       char *metafile;
       unsigned start, num;

       int CGM_appendFrames(metafile, start, num)
       char *metafile;
       unsigned start, num;

DESCRIPTION

       The  argument  cgm_fd refers to a valid file descriptor created for reading or writing, as
       appropriate by CGM_open.  CGM_read,  CGM_directory,   CGM_getInstr  and  CGM_flushGetInstr
       require  a file descriptor open for reading. CGM_write, CGM_getInstr,CGM_flushGetInstr and
       CGM_flushOutputInstr require a Cgm_fd open  for  writing.  CGM_close  and  CGM_lseek  will
       accept any valid Cgm_fd.

       The  size  argument refers to the CGM record size in bytes.  For an NCAR CGM this value is
       1440.

       buf is a pointer to user allocated memory of size size. This  storage  will  be  used  for
       buffering input and output of CGM_read and CGM_write respectively.

       The  dir  argument  is  a  pointer  to a Directory structure created with CGM_directory or
       CGM_initMetaEdit.  dir is a private resource that should NOT be directly modified  by  the
       user. A set of convenience macros is provided for this purpose in cgm_tools.h.

       The  start, num and target arguments are used to address frame numbers in a metafile being
       edited  with  one  of  the  commands:  CGM_copyFrames,  CGM_deleteFrames,  CGM_readFrames,
       CGM_moveFrames,  CGM_writeFrames  and  CGM_mergeFrames.   The  start argument is the first
       frame in a sequence of num frame(s) to perform the editing operation on. target is similar
       to start and is used by commands that require two frame addresses such as copy. Addressing
       begins at zero.

       CGM_open
              This command is modeled after the unix open command. It will open a CGM for reading
              or  writing as specified by the flags argument and return a Cgm_fd file descriptor.
              The flags and open parameters are passed directly on to the  system  open  command.
              For a detailed explanation of these two arguments see open(2).

       CGM_close
              Delete a file descriptor. The inverse of CGM_open. See close(2).

       CGM_read
              CGM_read  attempts  to  read  size  bytes  from  the  object referenced through the
              descriptor cgm_fd. size is set at the creation  of  cgm_fd  by  CGM_open.  CGM_read
              returns  the  number  of  bytes  successfully read. A zero is returned on EOF and a
              negative number implies an error occurred.  The unix system call read is called  by
              CGM_read. See read(2).

       CGM_write
              Attempts to write a single record of size bytes from buf from the object referenced
              by cgm_edit where size is the record size parameter provided  at  the  creation  of
              cgm_fd.  write  returns the number of bytes successfully written. A negative return
              number implies an error  occurred.   The  unix  system  call  write  is  called  by
              CGM_write. See write(2).

       CGM_lseek
              Advance  the file pointer of cgm_fd to offset bytes. Upon successful completion the
              current file pointer offset is returned. A negative return value is an error.   The
              unix system call lseek is called by CGM_lseek. See lseek(2).

       CGM_directory
              Create a table of contents for the metafile referenced by cgm_fd.  Return a pointer
              to this table of type Directory. The contents of the directory  include  number  of
              metafiles, number of frames, record offset for each frame, frame length in records,
              optional frame description and metafile status. These fields are meant to  be  read
              only  and  should  only  be  referenced  by  the  convenience  macros  provided  in
              cgm_tools.h. A NULL pointer is returned on failure.

       CGM_freeDirectory
              Free memory allocated to a directory created by CGM_directory or CGM_initMetaEdit.

       CGM_printDirectory
              Print the contents of a directory pointed to by dir to the standard output.

       CGM_getInstr,
              Fetch the next instruction in file referenced by cgm_edit  and convert  it  into  a
              usable  format  pointed  to  by  instr.   CGM_getInstr provides an interface to the
              metafile for extracting CGM elements. The user  need  not  be  concerned  with  the
              binary  format  of  the  metafile.  The  fields  of  the  Instr are as described in
              cgm_tools.h.  The user should note that the maximum allowable data length  returned
              in  a single invocation is 32760 bytes. The CGM standard allows upto 32767 bytes to
              be stored in a single instruction. But 32767 is not a nice  number  to  work  with.
              Should  the  data  length of a CGM instruction exceed 32760 bytes, indicated by the
              boolean more flag, the next invocation of CGM_getInstr will  return  the  remaining
              data  up  to  the  same  limit,  etc.  CGMgetInstr requires a valid Cgm_fd open for
              reading.  For a description on CGM see the ANSI standard.

       CGM_flushGetInstr
              Flush the input buffer used by CGM_getInstr. CGM_getInstr buffers the  contents  of
              the CGM and only performs actual reads as necessary. If the user desires other then
              sequential read access to a CGM it becomes necessary  to  flush  the  input  buffer
              before reading from a new location.

       CGM_putInstr
              The analog to CGM_getInstr. This function buffers CGM instructions to be written to
              a CGM referenced by cgm_fd. Again the user need not be concerned  with  the  binary
              format  of  the  file.  Writes  are  performed  sequentially in record size size as
              specified during the creation of cgm_fd. The same data length constraints that  are
              placed  on  CGM_getInstr  hold  for  CGM_putInstr.  If  the  user  wants  to output
              instructions with a data length greater than 32760 bytes  then  the  data  must  be
              broken up into blocks no greater than this size. The user must also set the boolean
              more flag in the Instr. cgm_fd must be a valid file descriptor  open  for  writing.
              For a description of the fields of the Instr see the file cgm_tools.h.

       CGM_flushOutputInstr
              Flush  the output buffer used by CGM_putInstr for the file referenced by cgm_fd. It
              is necessary to explicitly flush the output buffer used by CGM_putInstr before  the
              file  is  closed  or any random access is performed. Otherwise not all CGM elements
              will actually get written.

       CGM_initMetaEdit
              Initialize a metafile for editing. This  is  the  initialization  routine  for  the
              higher   level   editing   routines  contained  in  this  package:  CGM_copyFrames,
              CGM_deleteFrames, CGM_readFrames, CGM_moveFrames,  CGM_writeFile,  CGM_writeFrames,
              and  CGM_mergeFrames.   These routines only work on one metafile at a time (the one
              named in  CGM_initMetaEdit.  Invoking  this  routine  for  a  second  time  without
              explicitly  saving  any  changes  will  have  the  effect of loading a new file and
              discarding all changes  made  in  the  previous  file.   CGM_initMetaEdit  and  all
              proceeding  editing  functions  that make changes to the file return a pointer to a
              Directory as a convenience that allows the user to examine the state of  the  file.
              The  contents of the directory are private and should NOT be changed by the user. A
              set of macros is provided in cgm_tools.h to be used for retrieving the  directory's
              contents.  Note:  no  changes  are  actually  made  to  the  edit file unless it is
              explicitly overwritten with either CGM_writeFile or CGM_writeFrames.

       CGM_termMetaEdit
              Terminate the editing session started with CGM_initMetaEdit.  This  routine  should
              be  called  after any editing changes have been saved, if desired to save them, and
              before exiting the editing session.  CGM_termMetaEdit frees valuable resources.

       CGM_copyFrames
              Copy num frames beginning with start to the frame addressed by target. If target is
              already  occupied then the source frames are inserted in its place while the target
              frame, and all proceeding frames, are  advanced.  CGM_copy  operates  on  the  file
              initialized by CGM_initMetaEdit (the edit file). On successful completion a pointer
              to the current directory is returned. On error a NULL pointer is returned.

       CGM_deleteFrames
              Delete num frames from the edit file  starting  with  frame  start.  On  successful
              completion  a pointer to the current directory is returned. On error a NULL pointer
              is returned.

       CGM_mergeFrames
              Overwrite the contents of frame addressed bottom with the union  of  the  frame  at
              location  bottom  and  the  frame  at  location top.  The effect of this command is
              equivalent to drawing the top frame on top of the bottom frame. It is not  a  union
              in  the  true sense of the word.  On successful completion a pointer to the current
              directory is returned. On error a NULL pointer is returned.

       CGM_moveFrames
              Move a block of num frames from the edit file starting with with frame start to the
              position occupied by frame target On successful completion a pointer to the current
              directory is returned. On error a NULL pointer is returned.

       CGM_readFrames
              Read num frames from metafile file starting with frame start.  Insert the frames at
              address target in the edit file.  On successful completion a pointer to the current
              directory is returned. On error a NULL pointer is returned.

       CGM_validCGM
              Determine whether a file is a valid NCAR CGM or not. This function performs  a  few
              simple  diagnostics  in  an effort to determine whether a given file is in the NCAR
              CGM format. The tests performed are not rigorous and it  is  conceivable  that  the
              information  retrieved  is incorrect.  A return of 1 indicates a valid NCAR CGM.  A
              return of 0 indicates the file is not a NCAR CGM. A return of -1 indicates an error
              occurred and the global variable `errno' is set accordingly.

       CGM_writeFile
              Write  the entire contents of the current edit file to file.  CGM_writeFile returns
              the integer one on success and a negative number on failure.

       CGM_writeFrames
              Write a block of num frames starting with frame start to file.  The  source  frames
              come  from  the  edit file.  Note: CGM frames are contained in a wrapper made up of
              CGM delimiter elements. The file created by CGM_writeFrames will  use  the  wrapper
              provided  by  the  current edit file. Thus if a file foo contains n frames that are
              read into an editing session with a file goo and then these same frames are written
              out  to  a  file  zoid,  zoid  may  or  may  not  be  the same as the original foo.
              CGM_writeFrames returns the integer  one  on  success  and  a  negative  number  on
              failure.

       CGM_appendFrames
              Append  a  block of num frames starting with frame start to file. file must already
              exist and be a valid NCAR CGM.  CGM_appendFrames returns the integer one on success
              and a negative number on failure.

SEE ALSO

       ANSI X3.122 Computer Graphics Metafile for the Storage and Transfer of Picture Description
       Information.

BUGS

       CGMs with more the one metafile stored in the are not guaranteed to work.

       Should not have to explicitly flush the output buffer for CGM_getInstr.   This  should  be
       handled automatically when the file is closed.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research

       The use of this Software is governed by a License Agreement.