complete documentation of stdin.* and stdout.*
authorAndre <maan@p133.(none)>
Tue, 13 Jun 2006 01:53:48 +0000 (03:53 +0200)
committerAndre <maan@p133.(none)>
Tue, 13 Jun 2006 01:53:48 +0000 (03:53 +0200)
stdin.c
stdin.h
stdout.c
stdout.h

diff --git a/stdin.c b/stdin.c
index d33be35..b86fbbb 100644 (file)
--- a/stdin.c
+++ b/stdin.c
@@ -1,3 +1,23 @@
+/*
+ * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ *
+ *     This program is free software; you can redistribute it and/or modify
+ *     it under the terms of the GNU General Public License as published by
+ *     the Free Software Foundation; either version 2 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU General Public License for more details.
+ *
+ *     You should have received a copy of the GNU General Public License
+ *     along with this program; if not, write to the Free Software
+ *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
+ */
+
+/** \file stdin.c functions that deal with reading from stdin */
+
 #include "para.h"
 #include "string.h"
 #include "list.h"
 #include "error.h"
 #include "stdin.h"
 
+/**
+ * the pre_select function of the stdin task
+ *
+ * \param s the scheduler this task was registered to
+ * \param t the task structure of the stdin task
+ *
+ * This function is always successful. If there is space left in the
+ * buffer of the stdin task, it adds \a STDIN_FILENO to the read fd set
+ * of \a s.
+ */
 void stdin_pre_select(struct sched *s, struct task *t)
 {
        struct stdin_task *sit = t->private_data;
-       if (sit->loaded < sit->bufsize)
-               para_fd_set(STDIN_FILENO, &s->rfds, &s->max_fileno);
-       t->ret = 1; /* success */
+       t->ret = 1;
+       sit->check_fd = 0;
+       if (sit->loaded >= sit->bufsize)
+               return;
+       sit->check_fd = 1;
+       para_fd_set(STDIN_FILENO, &s->rfds, &s->max_fileno);
 }
 
 static void stdin_default_event_handler(struct task *t)
@@ -20,13 +53,24 @@ static void stdin_default_event_handler(struct task *t)
        unregister_task(t);
 }
 
+/**
+ * the post select function of the stdin task
+ *
+ * \param s the scheduler this task was registered to
+ * \param t the task structure of the stdin task
+ *
+ * This function checks if \a STDIN_FILENO was included by in the read fd set
+ * of \a s during the previous pre_select call.  If yes, and STDIN_FILENO
+ * appeears to be readable, data is read from stdin into the buffer of the
+ * stdin task.
+ */
 void stdin_post_select(struct sched *s, struct task *t)
 {
        struct stdin_task *sit = t->private_data;
        ssize_t ret;
 
        t->ret = 1;
-       if (sit->loaded >= sit->bufsize)
+       if (!sit->check_fd)
                return;
        if (!FD_ISSET(STDIN_FILENO, &s->rfds))
                return;
@@ -42,6 +86,16 @@ void stdin_post_select(struct sched *s, struct task *t)
                sit->eof = 1;
 }
 
+/**
+ * initialize a stdin task structure with default values
+ *
+ * \param sit the stdin task structure
+ *
+ * This fills in the pre/post select function poinzters of the task structure
+ * given by \a sot. It also sets up a default error handler which unregisters
+ * the task. Moreover, \a loaded and \a eof are set to zero and \a bufsize is
+ * initialized to 16 KB (but no buffer is allocated).
+ */
 void stdin_set_defaults(struct stdin_task *sit)
 {
        sit->bufsize = 16 * 1024,
diff --git a/stdin.h b/stdin.h
index b9ee68b..a36b988 100644 (file)
--- a/stdin.h
+++ b/stdin.h
@@ -19,7 +19,7 @@
 /** \file stdin.h the stdin task structure and exported symbols from stdin.c */
 
 /**
- * the task structure used when reading from stdin
+ * the task structure used for reading from stdin
  */
 struct stdin_task {
        /** input buffer */
@@ -28,9 +28,11 @@ struct stdin_task {
        size_t bufsize;
        /** number of bytes currently loaded in \a buf */
        size_t loaded;
+       /** whether STDIN_FILENO was included in the read fd set */
+       int check_fd;
        /** the task structure */
        struct task task;
-       /** non-zero if a read from stdin returned zero */
+       /** non-zero on read error, or if a read from stdin returned zero */
        int eof;
 };
 
index e13d0f1..25402b8 100644 (file)
--- a/stdout.c
+++ b/stdout.c
@@ -33,9 +33,8 @@
  * \param s the scheduler this task was registered to
  * \param t the task structure of the stdout task
  *
- * This function is always successful. If there is data
- * available in the input buffer, it adds the STDOUT_FILENO
- * to the write fd set of \a s.
+ * This function is always successful. If there is data available in the input
+ * buffer, it adds \a STDOUT_FILENO to the write fd set of \a s.
  */
 void stdout_pre_select(struct sched *s, struct task *t)
 {
@@ -61,9 +60,10 @@ void stdout_pre_select(struct sched *s, struct task *t)
  * \param s the scheduler this task was registered to
  * \param t the task structure of the stdout task
  *
- * This function checks if STDOUT_FILENO was included by in the write fd set of
- * \a s during the previous pre_select call.  If yes, and STDOUT_FILENO appeears
- * to be writable, the data loaded in the input buffer is written to stdout.
+ * This function checks if \a STDOUT_FILENO was included by in the write fd set
+ * of \a s during the previous pre_select call.  If yes, and STDOUT_FILENO
+ * appeears to be writable, the data loaded in the input buffer is written to
+ * stdout.
  */
 void stdout_post_select(struct sched *s, struct task *t)
 {
@@ -97,10 +97,9 @@ static void stdout_default_event_handler(struct task *t)
  *
  * \param sot the stdout task structure
  *
- * This fills in the pre/post select function poinzters of the task
- * structure given by \a sot. It also sets up a default error handler
- * which unregisteres the task on errors and clears the eof flag of
- * \a sot.
+ * This fills in the pre/post select function poinzters of the task structure
+ * given by \a sot. It also sets up a default error handler which unregisters
+ * the task on errors and clears the eof flag of \a sot.
  */
 void stdout_set_defaults(struct stdout_task *sot)
 {
index 4dafafd..1fe09f1 100644 (file)
--- a/stdout.h
+++ b/stdout.h
@@ -1,11 +1,40 @@
-/** \file stdout.h common code for uitlities that write to stdout */
+/*
+ * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ *
+ *     This program is free software; you can redistribute it and/or modify
+ *     it under the terms of the GNU General Public License as published by
+ *     the Free Software Foundation; either version 2 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU General Public License for more details.
+ *
+ *     You should have received a copy of the GNU General Public License
+ *     along with this program; if not, write to the Free Software
+ *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
+ */
+
+/** \file stdout.h the stdout task structure and exported symbols from stdout.c */
+
+/**
+ * the task structure used for writing to stdout
+ */
 struct stdout_task {
+       /** pointer to the data buffer */
        char *buf;
+       /** the size of \a buf */
        size_t *bufsize;
+       /** number of bytes loaded in \a buf */
        size_t *loaded;
+       /** pointer to the eof flag of the feeding task */
        int *input_eof;
+       /** non-zero if a write error occured */
        int eof;
+       /** the task structure */
        struct task task;
+       /** whether STDOUT_FILENO was included in the write fd set */
        int check_fd;
 };