<commit_before>
=encoding utf8

=head1 Title

DRAFT: Synopsis 16: IPC / IO / Signals

=head1 Version

 Author:        <NAME> <<EMAIL>>
 Maintainer:    <NAME> <<EMAIL>>
 Contributions: 
 Date:          12 Sep 2006
 Last Modified: 14 Sep 2006
 Version:       9 

This is a draft document. Many of these functions will work as in Perl 5,
except we're trying to rationalize everything into packages.  For now you can
assume most of the important ones will automatically be in the * namespace.

As a starting point, you can help by finding the official Perl 5 documentation
for these functions and copying it here. 

=head1 Filehandles, files, and directories

=over 4

=item -X

=item chown

=item chmod LIST
X<chmod> X<permission> X<mode>

Changes the permissions of a list of files.  The first element of the
list must be the numerical mode, which should probably be an octal
number, and which definitely should I<not> be a string of octal digits:
C<0644> is okay, C<'0644'> is not.  Returns the number of files
successfully changed.  See also L</oct>, if all you have is a string.

    $cnt = chmod 0755, 'foo', 'bar';
    chmod 0755, @executables;
    $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
                                             # --w----r-T
    $mode = '0644'; chmod oct($mode), 'foo'; # this is better
    $mode = 0644;   chmod $mode, 'foo';      # this is best

=item closedir

 closedir (IO::Dir $dir)  
 $dir.closedir

Closes a directory opened by C<opendir> and returns the success of that
system call.

=item fcntl

=item glob

=item ioctl

=item link

=item listen

=item lstat

=item mkdir

=item open

    # Read
    my $fh = open($filename);

    # Write
    my $fh = open($filename, :w);

=item opendir EXPR

  my $dir = opendir('.');

Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
C<seekdir>, C<rewinddir>, and C<closedir>.  Returns an C<IO::Dir> object if
successful.

=item readdir

 readdir (IO::Dir $dir)  
 $dir.readdir

Returns the next directory entry for a directory opened by C<opendir>.
If used in list context, returns all the rest of the entries in the
directory.  If there are no more entries, returns an undefined value in
scalar context or a null list in list context.

If you're planning to filetest the return values out of a C<readdir>, you'd
better prepend the directory in question.  Otherwise, because we didn't
C<chdir> there, it would have been testing the wrong file.

=item readlink

=item rename

=item rewinddir

 rewinddir (IO::Dir $dir)  
 $dir.rewinddir

Sets the current position to the beginning of the directory for the
C<readdir> routine on DIRHANDLE.

=item rmdir

=item stat

=item symlink

=item syscall

=item sysopen

=item umask

=item unlink

=item utime

=back

=head1 Input and Output

=item getc FILEHANDLE

Returns the next character from the input file attached to FILEHANDLE,
or the undefined value at end of file, or if there was an error (in
the latter case C<$!> is set). 

=head1 Unfiled

=over 4

=item fileno

=item flock

=item getpeername

=item connect

=item eof

=item close

=item accept

=item /[get|set][host|net|proto|serv|sock].*/
<commit_msg>IO.pod     Bring over the spec for 'close' from Perl 5.     Changed $? to $! (TimToady++), and trimmed out     the part about SIGPIPE, which is still unspec'ed.<commit_after>
=encoding utf8

=head1 Title

DRAFT: Synopsis 16: IPC / IO / Signals

=head1 Version

 Author:        <NAME> <<EMAIL>>
 Maintainer:    <NAME> <<EMAIL>>
 Contributions: 
 Date:          12 Sep 2006
 Last Modified: 14 Sep 2006
 Version:       10

This is a draft document. Many of these functions will work as in Perl 5,
except we're trying to rationalize everything into packages.  For now you can
assume most of the important ones will automatically be in the * namespace.

As a starting point, you can help by finding the official Perl 5 documentation
for these functions and copying it here. 

=head1 Filehandles, files, and directories

=over 4

=item -X

=item chown

=item chmod LIST
X<chmod> X<permission> X<mode>

Changes the permissions of a list of files.  The first element of the
list must be the numerical mode, which should probably be an octal
number, and which definitely should I<not> be a string of octal digits:
C<0644> is okay, C<'0644'> is not.  Returns the number of files
successfully changed.  See also L</oct>, if all you have is a string.

    $cnt = chmod 0755, 'foo', 'bar';
    chmod 0755, @executables;
    $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
                                             # --w----r-T
    $mode = '0644'; chmod oct($mode), 'foo'; # this is better
    $mode = 0644;   chmod $mode, 'foo';      # this is best

=item close FILEHANDLE

Closes the file or pipe associated with the file handle, returning
true only if IO buffers are successfully flushed and closes the system
file descriptor.  Closes the currently selected filehandle if the
argument is omitted.

You don't have to close FILEHANDLE if you are immediately going to do
another C<open> on it, because C<open> will close it for you.  (See
C<open>.)  However, an explicit C<close> on an input file resets the line
counter (C<$.>), while the implicit close done by C<open> does not.

If the file handle came from a piped open, C<close> will additionally
return false if one of the other system calls involved fails, or if the
program exits with non-zero status.  (If the only problem was that the
program exited non-zero, C<$!> will be set to C<0>.)  Closing a pipe
also waits for the process executing on the pipe to complete, in case you
want to look at the output of the pipe afterwards, and
implicitly puts the exit status value of that command into C<$!>.

=item closedir

 closedir (IO::Dir $dir)  
 $dir.closedir

Closes a directory opened by C<opendir> and returns the success of that
system call.

=item fcntl

=item glob

=item ioctl

=item link

=item listen

=item lstat

=item mkdir

=item open

    # Read
    my $fh = open($filename);

    # Write
    my $fh = open($filename, :w);

=item opendir EXPR

  my $dir = opendir('.');

Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
C<seekdir>, C<rewinddir>, and C<closedir>.  Returns an C<IO::Dir> object if
successful.

=item readdir

 readdir (IO::Dir $dir)  
 $dir.readdir

Returns the next directory entry for a directory opened by C<opendir>.
If used in list context, returns all the rest of the entries in the
directory.  If there are no more entries, returns an undefined value in
scalar context or a null list in list context.

If you're planning to filetest the return values out of a C<readdir>, you'd
better prepend the directory in question.  Otherwise, because we didn't
C<chdir> there, it would have been testing the wrong file.

=item readlink

=item rename

=item rewinddir

 rewinddir (IO::Dir $dir)  
 $dir.rewinddir

Sets the current position to the beginning of the directory for the
C<readdir> routine on DIRHANDLE.

=item rmdir

=item stat

=item symlink

=item syscall

=item sysopen

=item umask

=item unlink

=item utime

=back

=head1 Input and Output

=item getc FILEHANDLE

Returns the next character from the input file attached to FILEHANDLE,
or the undefined value at end of file, or if there was an error (in
the latter case C<$!> is set). 

=head1 Unfiled

=over 4

=item fileno

=item flock

=item getpeername

=item connect

=item eof


=item accept

=item /[get|set][host|net|proto|serv|sock].*/

{'fraction_non_alphanumeric': 0.08199786324786325, 'fraction_numerical': 0.014556623931623932, 'mean_word_length': 3.479066985645933, 'pattern_counts': {'":': 0, '<': 63, '<?xml version=': 0, '>': 63, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6278995', 'n_tokens_mistral': 2456, 'n_tokens_neox': 2316, 'n_words': 1111}