TNF Library Functions                   tnfctlbufferalloc(3TNF)



NAME
     tnfctlbufferalloc,  tnfctlbufferdealloc  -  allocate  or
     deallocate a buffer for trace data

SYNOPSIS
     cc [ flag ... ] file ... -ltnfctl [ library ... ]
     #include 
     tnfctlerrcodet tnfctlbufferalloc(tnfctlhandlet *hndl,
          const char *tracefilename, sizet tracebuffersize);


     tnfctlbufferdealloc(tnfctlhandlet *hndl);


DESCRIPTION
     tnfctlbufferalloc() allocates  a  buffer  to  which  trace
     events  are  logged.  When tracing a process using a  tnfctl
     handle       returned       by        tnfctlpidopen(3TNF),
     tnfctlexecopen(3TNF),    tnfctlindirectopen(3TNF),   and
     tnfctlinternalopen(3TNF)), tracefilename is the name  of
     the  trace  file  to which trace events should be logged. It
     can be an absolute path specification  or  a  relative  path
     specification. If it is relative, the current working direc-
     tory of the process that is  calling   tnfctlbufferalloc()
     is  prefixed  to   tracefilename.  If the named trace file
     already exists, it is overwritten. For kernel tracing,  that
     is,      for     a     tnfctl     handle     returned     by
     tnfctlkernelopen(3TNF), trace events are logged to a trace
     buffer  in  memory;  therefore,  tracefilename is ignored.
     Use tnfxtract(1) to extract a kernel buffer into a file.


     tracebuffersize is the size in bytes of the  trace  buffer
     that should be allocated. An error is returned if an attempt
     is made to  allocate  a  buffer  when  one  already  exists.
     tnfctlbufferalloc()  affects  the  trace  attributes;  use
     tnfctltraceattrsget(3TNF) to get the latest trace  attri-
     butes after a buffer is allocated.


     tnfctlbufferdealloc() is used to deallocate a kernel trace
     buffer  that is no longer needed. hndl must be a kernel han-
     dle, returned by tnfctlkernelopen(3TNF). A process's trace
     file  cannot  be  deallocated using tnfctlbufferdealloc().
     Instead, once  the  trace  file  is  no  longer  needed  for
     analysis  and  after   the  process  being traced exits, use
     rm(1) to remove the trace file. Do not remove the trace file
     while   the   process   being   traced   is   still   alive.
     tnfctlbufferdealloc() affects the  trace  attributes;  use
     tnfctltraceattrsget(3TNF)  to get the latest trace attri-
     butes after a buffer is deallocated.




SunOS 5.11           Last change: 4 Mar 1997                    1






TNF Library Functions                   tnfctlbufferalloc(3TNF)



     For   a   complete   discussion   of    tnf   tracing,   see
     tracing(3TNF).

RETURN VALUES
     tnfctlbufferalloc()  and  tnfctlbufferdealloc()   return
     TNFCTLERNONE upon success.

ERORS
     The following error codes apply to tnfctlbufferalloc():

     TNFCTLERBUFEXISTS       A buffer already exists.


     TNFCTLERACES           Permission  denied;   could   not
                                create a trace file.


     TNFCTLERSIZETOSMAL    The  tracebuffersize  requested
                                is smaller than the minimum trace
                                buffer    size    needed.     Use
                                traceminsize  of  trace  attri-
                                butes                          in
                                tnfctltraceattrsget(3TNF)   to
                                determine the minimum size of the
                                buffer.


     TNFCTLERSIZETOBIG      The requested trace file size  is
                                too big.


     TNFCTLERBADARG          tracefilename is  NUL  or  the
                                absolute path name is longer than
                                MAXPATHLEN.


     TNFCTLERALOCFAIL       A   memory   allocation   failure
                                occurred.


     TNFCTLERINTERNAL        An internal error occurred.



     The following error codes apply to tnfctlbufferdealloc():

     TNFCTLERBADARG        hndl is not a kernel handle.


     TNFCTLERNOBUF         No buffer exists to deallocate.





SunOS 5.11           Last change: 4 Mar 1997                    2






TNF Library Functions                   tnfctlbufferalloc(3TNF)



     TNFCTLERBADEALOC    Cannot deallocate  a  trace  buffer
                              unless   tracing  is  stopped.  Use
                              tnfctltracestateset(3TNF)     to
                              stop tracing.


     TNFCTLERINTERNAL      An internal error occurred.


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWtnfc                    
    
     MT Level                     MT-Safe                     
    


SEE ALSO
     prex(1),     rm(1),      tnfxtract(1),      TNFPROBE(3TNF),
     libtnfctl(3TNF),                     tnfctlexecopen(3TNF),
     tnfctlindirectopen(3TNF),      tnfctlinternalopen(3TNF),
     tnfctlkernelopen(3TNF),             tnfctlpidopen(3TNF),
     tnfctltraceattrsget(3TNF), tracing(3TNF), attributes(5)

























SunOS 5.11           Last change: 4 Mar 1997                    3