Message-Id: <3.0.1.32.19980201172905.007d1520@yacker.xiotech.com>
Date: Sun, 01 Feb 1998 17:29:05 -0600
To: djgpp-workers AT delorie DOT com
From: Randy Maas <randym AT acm DOT org>
Subject: proposed changes to fsext.txh
Cc: eliz AT is DOT elta DOT co DOT il
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="=====================_886397345==_"
Precedence: bulk

--=====================_886397345==_
Content-Type: text/plain; charset="us-ascii"

I've attached some diffs to fsext.txh.  I hope they are an improvement on
the current documentation of __FSEXT_{set,get}_data.  I've tried to provide
a somewhat realistic example, although it is not very short.  I've
sprinkled the example with comments, making it a little bigger.

Randy
randym AT acm DOT org
--=====================_886397345==_
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: attachment; filename="fdiff"

*** src/libc/fsext/fsext.txh~1	Fri Jan  2 00:28:02 1998
--- src/libc/fsext/fsext.txh	Sun Feb  1 17:22:46 1998
***************
*** 291,300 ****
--- 291,389 ----
  to store a descriptor-specific pointer that can later be retrieved by
  @ref{__FSEXT_get_data}.  The pointer is not otherwise used.
  
+ This is useful when writing an extension that may be handling several
+ open psuedo-files.  @code{__FSEXT_set_data} can be used when creating or
+ opening the file to store a pointer to data about the specific file.  Later,
+ when specific operation needs to be done (e.g. read, write, etc.) a
+ pointer to psuedo-file associated with the file descriptor can  be fetched
+ with @code{__FSEXT_get_data}.
+ 
  @subheading Return Value
  
  Returns the pointer you passed it, or NULL if there was an error.
  
+ @subheading Example
+ typedef struct
+ @{
+    void* Ptr;
+    off_t Current_Ofs;
+    size_t Size;
+ @} _mem_file_t;
+ 
+ int my_fsext(__FSEXT_Fnumber Op, int* RV, va_list Args)
+ @{
+    const char* Path;
+    void* Buffer;
+    size_t Size;
+    int fd;
+    _mem_file_t* MPtr;
+ 
+    switch (Op)
+    @{
+       case __FSEXT_creat:
+        /* Create a new memory file */
+ 
+        Path = va_list(Args, const char*);
+ 
+        /* Check to see if we should create a new file */
+        if (strnicmp("/tmp/", Path, 5) != 0) return 0;
+ 
+        /* Allocate some memory to keep info on our fake file */
+        MPtr = malloc(sizeof(_mem_file_t));
+        if (!MPtr) return 0;
+ 
+        memset(MPtr, 0, sizeof(_mem_file_t));
+ 
+        /* Get a file descriptor we can use */
+        fd = __FSEXT_alloc_fd(my_fsext);
+        if (fd < 0)
+        @{
+           free(MPtr);
+           return 0;
+        @}
+ 
+        /* Now store our note about this file descriptor so we can lookup it
+           up quickly later. */
+        __FSEXT_set_data(fd, MPtr);
+ 
+        /* Return the file descriptor
+        *RV = fd;
+        return 1;
+ 
+       case __FSEXT_read:
+        /* Read from our memory file. */
+        fd = va_list(Args, int);
+        Buffer = va_list(Args, void*);
+        Size = va_list(Args, size_t);
+ 
+        /* Look up the information about this file */
+        MPtr = __FSEXT_get_data(fd);
+        if (!MPtr)
+        @{
+            *RV = -1;
+            return 1;
+        @}
+ 
+        if (MPtr->Current_Ofs >= MPtr->Size)
+        @{
+            *RV = 0;
+            return 1;
+        @}
+ 
+        if (Size > (MPtr->Size - MPtr->Current_Ofs))
+         Size = MPtr->Size - MPtr->Current_Ofs;
+ 
+        memcpy(Buffer, (char*) MPtr->Ptr+MPtr->Current_Ofs, Size);
+        MPtr->Current_Ofs += Size;
+ 
+        *RV = Size;
+        return 1;
+        
+        ...
+     @}
+ @}
+     
+ 
  @c ----------------------------------------------------------------------
  @node __FSEXT_get_data, file system
  @subheading Syntax
***************
*** 311,317 ****
--- 400,409 ----
  to retrieve a descriptor-specific pointer that was previously stored
  by @ref{__FSEXT_set_data}.  The pointer is not otherwise used.
  
+ @pxref{__FSEXT_set_data} for an example of how this may be used.
+ 
  @subheading Return Value
  
  Returns the stored pointer, or NULL if there was an error (or no
  pointer had been stored).

--=====================_886397345==_
Content-Type: text/plain; charset="us-ascii"



--=====================_886397345==_--