[LON-CAPA-cvs] cvs: loncom /lonnet/perl lonnet.pm

[raeburn]

raeburn		Mon Oct 17 15:35:07 2011 EDT

  Modified files:              
    /loncom/lonnet/perl	lonnet.pm 
  Log:
  - POD for &dirlist().
  
  
Index: loncom/lonnet/perl/lonnet.pm
diff -u loncom/lonnet/perl/lonnet.pm:1.1136 loncom/lonnet/perl/lonnet.pm:1.1137
--- loncom/lonnet/perl/lonnet.pm:1.1136	Mon Oct 17 12:41:39 2011
+++ loncom/lonnet/perl/lonnet.pm	Mon Oct 17 15:35:07 2011
@@ -1,7 +1,7 @@
 # The LearningOnline Network
 # TCP networking package
 #
-# $Id: lonnet.pm,v 1.1136 2011/10/17 12:41:39 raeburn Exp $
+# $Id: lonnet.pm,v 1.1137 2011/10/17 15:35:07 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -11836,7 +11836,82 @@
 
 =item *
 
-dirlist($uri) : return directory list based on URI
+dirlist() : return directory list based on URI (first arg).
+
+Inputs: 1 required, 5 optional.
+
+=over
+
+=item 
+$uri - path to file in filesystem (starts: /res or /userfiles/). Required.
+
+=item
+$userdomain - domain of user/course to be listed. Extracted from $uri if absent. 
+
+=item
+$username -  username of user/course to be listed. Extracted from $uri if absent. 
+
+=item
+$getpropath - boolean: 1 if prepend path using &propath(). 
+
+=item
+$getuserdir - boolean: 1 if prepend path for "userfiles".
+
+=item 
+$alternateRoot - path to prepend in place of path from $uri.
+
+=back
+
+Returns: Array of up to two items.
+
+=over
+
+a reference to an array of files/subdirectories
+
+=over
+
+Each element in the array of files/subdirectories is a & separated list of
+item name and the result of running stat on the item.  If dirlist was requested
+for a file instead of a directory, the item name will be ''. For a directory 
+listing, if the item is a metadata file, the element will end &N&M 
+(where N amd M are either 0 or 1, corresponding to obsolete set (1), or
+default copyright set (1).  
+
+=back
+
+a scalar containing error condition (if encountered).
+
+=over
+
+=item 
+no_host (no homeserver identified for $username:$domain).
+
+=item 
+no_such_host (server contacted for listing not identified as valid host).
+
+=item 
+con_lost (connection to remote server failed).
+
+=item 
+refused (invalid $username:$domain received on lond side).
+
+=item 
+no_such_dir (directory at specified path on lond side does not exist). 
+
+=item 
+empty (directory at specified path on lond side is empty).
+
+=over
+
+This is currently not encountered because the &ls3, &ls2, 
+&ls (_handler) routines on the lond side do not filter out
+. and .. from a directory listing. 
+
+=back
+
+=back
+
+=back
 
 =item *