The TSfopen Family
******************

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

The ``fopen`` family of functions in C is normally used for reading
configuration files, since ``fgets`` is an easy way to parse files on a
line-by-line basis. The ``TSfopen`` family of functions aims at solving
the same problem of buffered IO and line at a time IO in a
platform-independent manner. The ``fopen`` family of C library functions
can only open a file if a file descriptor less than 256 is available.
Since Traffic Server often has more than 2000 file descriptors open at
once, however, the likelihood of an available file descriptor less than
256 very small. To solve this problem, the ``TSfopen`` family can open
files with descriptors greater than 256.

The ``TSfopen`` family of routines is not intended for high speed IO or
flexibility - they are blocking APIs (not asynchronous). For performance
reasons, you should not directly use these APIs on a Traffic Server
thread (when being called back on an HTTP hook); it is better to use a
separate thread for doing the blocking IO. The ``TSfopen`` family is
intended for reading and writing configuration information when
corresponding usage of the ``fopen`` family of functions is
inappropriate due to file descriptor and portability limitations. The
``TSfopen`` family of functions consists of the following:

-  :c:func:`TSfclose`

-  :c:func:`TSfflush`

-  :c:func:`TSfgets`

-  :c:func:`TSfopen`

-  :c:func:`TSfread`

-  :c:func:`TSfwrite`