Skip to content

Commit

Permalink
Atualizações de problemas detectados por qaxml.a, última tranche.
Browse files Browse the repository at this point in the history
  • Loading branch information
André L F S Bacci committed Aug 3, 2023
1 parent 5e6d31f commit 42b889d
Show file tree
Hide file tree
Showing 8 changed files with 355 additions and 215 deletions.
190 changes: 116 additions & 74 deletions reference/filesystem/functions/fwrite.xml
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: n/a Maintainer: diogo Status: ready --><!-- CREDITS: rarruda,ae -->
<!-- EN-Revision: bb6247b68128cab1b166b49a3a73a87f40333267 Maintainer: ae Status: ready --><!-- CREDITS: rarruda,diogo,ae -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fwrite">
<refnamediv>
<refname>fwrite</refname>
<refpurpose>Escrita binary-safe em arquivos</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>fwrite</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
<type class="union"><type>int</type><type>false</type></type><methodname>fwrite</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<simpara>
<function>fwrite</function> escreve o conteúdo da
<parameter>string</parameter> para o stream de arquivo apontado por
<parameter>handle</parameter>.
<function>fwrite</function> grava o conteúdo de
<parameter>data</parameter> no ponteiro de arquivo informado em
<parameter>stream</parameter>.
</simpara>
</refsect1>

Expand All @@ -26,13 +26,13 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<term><parameter>stream</parameter></term>
<listitem>
&fs.file.pointer;
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>string</parameter></term>
<term><parameter>data</parameter></term>
<listitem>
<para>
A string a ser escrita.
Expand All @@ -43,16 +43,9 @@
<term><parameter>length</parameter></term>
<listitem>
<para>
Se o argumento <parameter>comprimento</parameter> for dado, a escrita irá
parar depois que <parameter>comprimento</parameter> bytes tenham sido escritos ou
o final da <parameter>string</parameter> seja alcançado, o que vier
primeiro.
</para>
<para>
Observe que se o argumento <parameter>comprimento</parameter> for dado,
a opção de configuração <link
linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
será ignorada e nenhuma barra será removida da <parameter>string</parameter>.
Se <parameter>length</parameter> for um &integer;, a escrita irá parar
depois que<parameter>length</parameter> forem escritos, ou o
o fim de <parameter>data</parameter> for alcançado, o que ocorrer primeiro.
</para>
</listitem>
</varlistentry>
Expand All @@ -64,12 +57,105 @@
&reftitle.returnvalues;
<simpara>
<function>fwrite</function> retorna o número de bytes
escritos, ou &false; em caso de erro.
escritos, &return.falseforfailure;.
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
<function>fwrite</function> emite um <constant>E_WARNING</constant> em caso falhas.
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.0.0</entry>
<entry>
<parameter>length</parameter> pode ser null.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Exemplo de <function>fwrite</function></title>
<programlisting role="php">
<![CDATA[
<?php
$filename = 'test.txt';
$somecontent = "Acrescente isso no arquivo\n";
// Vamos garantir que o arquivo existe e pode ser escrito
if (is_writable($filename)) {
// Nesse exemplo estamos abrindo o $filename em modo append.
// O ponteiro do arquivo estará no final do arquivo
// e portanto é aqui que $somecontent será posicionado pelo fwrite().
if (!$fp = fopen($filename, 'a')) {
echo "Erro ao abrir o ($filename)";
exit;
}
// Escrever alguma coisa no arquivo.
if (fwrite($fp, $somecontent) === FALSE) {
echo "Erro ao escrever no arquivo ($filename)";
exit;
}
echo "Sucesso, escrito ($somecontent) no arquivo ($filename)";
fclose($fp);
} else {
echo "O arquivo não permite escrita";
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>

<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Escrever em um stream de rede pode acabar antes de toda a string ser transmitida.
O retorno de <function>fwrite</function> precisa ser inspecionado:
<programlisting role="php">
<![CDATA[
<?php
function fwrite_stream($fp, $string) {
for ($written = 0; $written < strlen($string); $written += $fwrite) {
$fwrite = fwrite($fp, substr($string, $written));
if ($fwrite === false) {
return $written;
}
}
return $written;
}
?>
]]>
</programlisting>
</para>
</note>

<note>
<para>
Em sistemas que diferenciam entre arquivos binários e texto
Expand All @@ -79,80 +165,35 @@
</note>
<note>
<para>
Se o <parameter>handle</parameter> foi aberto com <function>fopen</function>
Se o <parameter>stream</parameter> foi aberto com <function>fopen</function>
em modo de adição, escritas com <function>fwrite</function> são atômicas
(a não ser que o tamanho da <parameter>string</parameter> exceda o tamanho
(a não ser que o tamanho da <parameter>data</parameter> exceda o tamanho
de bloco do sistema de arquivos, em algumas plataformas, e contanto que o
arquivo esteja em um sistema de arquivos local). Sendo assim,
não há necessidade de bloquear um recurso com <function>flock</function> antes
de chamar <function>fwrite</function>; todos os dados serão escritos sem
interrupção.
de chamar <function>fwrite</function>; todos os dados serão escritos sem interrupção.
</para>
</note>
<note>
<para>
Se escrevendo duas vezes para o ponteiro do arquivo, então a informação
será adicionado ao final do contéudo do arquivo, significando que o exemplo
abaixo não funcionaria como esperado:
Se escrever duas vezes no ponteiro do arquivo, então a informação
será adicionado ao final do contéudo do arquivo:
<programlisting role="php">
<![CDATA[
<![CDATA[
<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);
// o conteúdo de 'data.txt' agora é 123 e não 23!
// O conteúdo de 'data.txt' é 123, e não 23
?>
]]>
</programlisting>
</para>
</note>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Um simples exemplo de <function>fwrite</function></title>
<programlisting role="php">
<![CDATA[
<?php
$filename = 'teste.txt';
$conteudo = "Acrescentar isso ao arquivo\n";
// Primeiro vamos ter certeza de que o arquivo existe e pode ser alterado
if (is_writable($filename)) {
// Em nosso exemplo, nós vamos abrir o arquivo $filename
// em modo de adição. O ponteiro do arquivo estará no final
// do arquivo, e é pra lá que $conteudo irá quando o
// escrevermos com fwrite().
if (!$handle = fopen($filename, 'a')) {
echo "Não foi possível abrir o arquivo ($filename)";
exit;
}
// Escreve $conteudo no nosso arquivo aberto.
if (fwrite($handle, $conteudo) === FALSE) {
echo "Não foi possível escrever no arquivo ($filename)";
exit;
}
echo "Sucesso: Escrito ($conteudo) no arquivo ($filename)";
fclose($handle);
} else {
echo "O arquivo $filename não pode ser alterado";
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
Expand All @@ -162,6 +203,7 @@ if (is_writable($filename)) {
<member><function>fsockopen</function></member>
<member><function>popen</function></member>
<member><function>file_get_contents</function></member>
<member><function>pack</function></member>
</simplelist>
</para>
</refsect1>
Expand Down
43 changes: 37 additions & 6 deletions reference/info/functions/get-magic-quotes-runtime.xml
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,59 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: n/a Maintainer: fernandoc Status: ready -->
<!-- EN-Revision: 62aa2694baf7fe904744a9b0f8a2a26e7fc3cf12 Maintainer: ae Status: ready --><!-- CREDITS: fernandoc,ae -->
<refentry xml:id="function.get-magic-quotes-runtime" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>get_magic_quotes_runtime</refname>
<refpurpose>Obtém a configuração ativa para magic_quotes_runtime</refpurpose>
</refnamediv>

<refsynopsisdiv>
&warn.deprecated.function-7-4-0.removed-8-0-0;
</refsynopsisdiv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>get_magic_quotes_runtime</methodname>
<type>false</type><methodname>get_magic_quotes_runtime</methodname>
<void/>
</methodsynopsis>
<simpara>
Retorna a configuração ativa para <link
linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>.
Sempre retorna &false;.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Retorna 0 se magic quotes runtime está off, 1 caso contrário.
Sempre retorna &false;.
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>7.4.0</entry>
<entry>
Esta função está obsoleta.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>

Expand All @@ -30,7 +62,6 @@
<para>
<simplelist>
<member><function>get_magic_quotes_gpc</function></member>
<member><function>set_magic_quotes_runtime</function></member>
</simplelist>
</para>
</refsect1>
Expand Down
4 changes: 0 additions & 4 deletions reference/info/ini.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -288,10 +288,6 @@
</listitem>
</varlistentry>

<!-- TODO: Removido nos originais, mas ainda referenciado em arquivos antigos no manual. -->
<varlistentry xml:id="ini.magic-quotes-gpc"><term><type>bool</type></term><listitem><para></para></listitem></varlistentry>
<varlistentry xml:id="ini.magic-quotes-runtime"><term><type>bool</type></term><listitem><para></para></listitem></varlistentry>

</variablelist>
</para>
</section>
Expand Down
8 changes: 3 additions & 5 deletions reference/mysql/functions/mysql-escape-string.xml
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 7f569e1f175adf1fbd0e462eba8d6bc82214c939 Maintainer: fernandoc Status: ready --><!-- CREDITS: adiel, enzogamads, fernandoc -->
<!-- EN-Revision: 62aa2694baf7fe904744a9b0f8a2a26e7fc3cf12 Maintainer: fernandoc Status: ready --><!-- CREDITS: adiel, enzogamads, fernandoc -->
<refentry xml:id="function.mysql-escape-string" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>mysql_escape_string</refname>
Expand Down Expand Up @@ -28,7 +28,7 @@
Esta função está obsoleta.
</para>
<para>
Esta função é idêntica a <function>mysql_real_escape_string</function>
Esta função é idêntica a <function>mysql_real_escape_string</function>
exceto que <function>mysql_real_escape_string</function> recebe um
manipulador de conexão e escapa a string de acordo com o conjunto de caracteres
atual. <function>mysql_escape_string</function> não recebe um
Expand All @@ -51,7 +51,7 @@
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Expand Down Expand Up @@ -98,8 +98,6 @@ String escapada: Zak\'s Laptop
<para>
<simplelist>
<member><function>mysql_real_escape_string</function></member>
<member><function>addslashes</function></member>
<member>A diretiva <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>.</member>
</simplelist>
</para>
</refsect1>
Expand Down
Loading

0 comments on commit 42b889d

Please sign in to comment.