--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Orb/Doxygen/DITA/plugins/apiref/sample/gets.dita	Thu Jan 21 17:29:01 2010 +0000
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE apiOperation PUBLIC "-//IBM//DTD DITA API Operation Reference Type//EN"
+ "../dtd/apiOperation.dtd">
+<apiOperation id="gets">
+<apiName>gets</apiName>
+<shortdesc>fgetc,  fgets,  getc,  getchar,	gets, ungetc - input of characters
+and strings.</shortdesc>
+<apiOperationDetail>
+<apiSyntax>
+<apiSyntaxText>#include &lt;stdio.h&gt;
+
+int <apiItemName>fgetc</apiItemName>(FILE *stream);
+char *<apiItemName>fgets</apiItemName>(char *s, int size, FILE *stream);
+int <apiItemName>getc</apiItemName>(FILE *stream);
+int <apiItemName>getchar</apiItemName>(void);
+char *<apiItemName>gets</apiItemName>(char *s);
+int <apiItemName>ungetc</apiItemName>(int c, FILE *stream);</apiSyntaxText>
+<apiSyntaxItem>
+<apiItemName>fgetc()</apiItemName>
+<apiDefNote>Reads the next character from stream and returns it as an unsigned
+char cast to an int, or EOF on end of file or error.</apiDefNote>
+</apiSyntaxItem>
+<apiSyntaxItem>
+<apiItemName>getc()</apiItemName>
+<apiDefNote>Is equivalent to <apioperation>fgetc()</apioperation> except that
+it may be implemented as a macro which evaluates stream more than once.</apiDefNote>
+</apiSyntaxItem>
+<apiSyntaxItem>
+<apiItemName>getchar()</apiItemName>
+<apiDefNote>Is equivalent to <apioperation>getc(stdin)</apioperation>.</apiDefNote>
+</apiSyntaxItem>
+<apiSyntaxItem>
+<apiItemName>gets()</apiItemName>
+<apiDefNote>Reads a line from stdin into the buffer pointed to by <codeph>s</codeph> until
+either a terminating newline or EOF, which it replaces with '\0'.  No check
+for buffer overrun is performed (see BUGS below).</apiDefNote>
+</apiSyntaxItem>
+<apiSyntaxItem>
+<apiItemName>fgets()</apiItemName>
+<apiDefNote>Reads in at most one less than size characters from stream and
+stores them into the buffer pointed to by <codeph>s</codeph>. Reading stops
+after an EOF or a newline. If a newline is read, it is stored into the buffer.
+A '\0' is stored after the last character in the buffer.</apiDefNote>
+</apiSyntaxItem>
+<apiSyntaxItem>
+<apiItemName>ungetc()</apiItemName>
+<apiDefNote>Pushes <codeph>c</codeph> back to stream, cast to unsigned char,
+where it is available for subsequent read operations.   Pushed-back characters
+will be returned in reverse order; only one pushback is guaranteed.</apiDefNote>
+</apiSyntaxItem>
+</apiSyntax>
+<apiDesc>Calls to the functions described here can be mixed with each other
+and with calls to other input functions from the stdio library for the same
+input stream.<p>For non-locking counterparts, see unlocked_stdio(3).</p></apiDesc>
+<section><title>Return value</title><sl>
+<sli><apioperation>fgetc()</apioperation>, <apioperation>getc()</apioperation> and <apioperation>getchar()</apioperation> return
+the character read as an unsigned char cast to an int or EOF on end of file
+or error. </sli>
+<sli><apioperation>gets()</apioperation> and <apioperation>fgets()</apioperation> return <codeph>s</codeph> on
+success, and NULL on error or  when  end of file occurs while no characters
+have been read. </sli>
+<sli><apioperation>ungetc()</apioperation> returns <codeph>c</codeph> on success,
+or EOF on error.</sli>
+</sl></section>
+<section><title>Conforming to</title>ANSI - C, POSIX.1</section>
+<section><title>Bugs</title>Never use <apioperation>gets()</apioperation>.
+ Because it is impossible to tell without knowing the data in advance how
+many characters <apioperation>gets()</apioperation>  will  read, and because <apioperation>gets()</apioperation> will
+continue to store characters past the end of the buffer, it is extremely dangerous
+to use.  It has been used to break computer security. Use <apioperation>fgets()</apioperation> instead. <p>It
+ is not advisable to mix calls to input functions from the stdio library with
+low-level calls to <apioperation>read()</apioperation> for the file descriptor
+associated with the input stream; the results will be undefined and very probably
+not what you want.</p></section>
+</apiOperationDetail>
+</apiOperation>