[SCM] Samba Shared Repository - branch master updated
Volker Lendecke
vlendec at samba.org
Wed Jun 14 12:22:01 UTC 2023
The branch, master has been updated
via 585e4cdd6c9 docs-xml: remove completely outdated Samba-Developers-Guide
from cac38aa3870 vfs: Remove vfs telldir/seekdir functions
https://git.samba.org/?p=samba.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit 585e4cdd6c98c91ea629f767e95e6c02ab5ed1af
Author: Björn Jacke <bj at sernet.de>
Date: Wed Jun 7 02:49:49 2023 +0200
docs-xml: remove completely outdated Samba-Developers-Guide
Signed-off-by: Bjoern Jacke <bjacke at samba.org>
Reviewed-by: Andrew Bartlett <abartlet at samba.org>
Reviewed-by: Volker Lendecke <vl at samba.org>
Autobuild-User(master): Volker Lendecke <vl at samba.org>
Autobuild-Date(master): Wed Jun 14 12:21:50 UTC 2023 on atb-devel-224
-----------------------------------------------------------------------
Summary of changes:
.../Samba-Developers-Guide/CodingSuggestions.xml | 239 --
docs-xml/Samba-Developers-Guide/Tracing.xml | 131 -
docs-xml/Samba-Developers-Guide/architecture.xml | 186 --
docs-xml/Samba-Developers-Guide/cifsntdomain.xml | 2934 --------------------
docs-xml/Samba-Developers-Guide/contributing.xml | 112 -
docs-xml/Samba-Developers-Guide/debug.xml | 323 ---
docs-xml/Samba-Developers-Guide/encryption.xml | 199 --
docs-xml/Samba-Developers-Guide/gencache.xml | 119 -
docs-xml/Samba-Developers-Guide/index.xml | 99 -
docs-xml/Samba-Developers-Guide/internals.xml | 442 ---
docs-xml/Samba-Developers-Guide/modules.xml | 176 --
docs-xml/Samba-Developers-Guide/packagers.xml | 54 -
docs-xml/Samba-Developers-Guide/parsing.xml | 241 --
docs-xml/Samba-Developers-Guide/printing.xml | 395 ---
docs-xml/Samba-Developers-Guide/rpc_plugin.xml | 90 -
docs-xml/Samba-Developers-Guide/unix-smb.xml | 316 ---
docs-xml/Samba-Developers-Guide/vfs.xml | 921 ------
docs-xml/Samba-Developers-Guide/wins.xml | 81 -
18 files changed, 7058 deletions(-)
delete mode 100644 docs-xml/Samba-Developers-Guide/CodingSuggestions.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/Tracing.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/architecture.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/cifsntdomain.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/contributing.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/debug.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/encryption.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/gencache.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/index.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/internals.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/modules.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/packagers.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/parsing.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/printing.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/rpc_plugin.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/unix-smb.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/vfs.xml
delete mode 100644 docs-xml/Samba-Developers-Guide/wins.xml
Changeset truncated at 500 lines:
diff --git a/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml b/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml
deleted file mode 100644
index 4adb8cb09b7..00000000000
--- a/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml
+++ /dev/null
@@ -1,239 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<chapter id="CodingSuggestions">
-<chapterinfo>
- <author>
- <firstname>Steve</firstname><surname>French</surname>
- </author>
- <author>
- <firstname>Simo</firstname><surname>Sorce</surname>
- </author>
- <author>
- <firstname>Andrew</firstname><surname>Bartlett</surname>
- </author>
- <author>
- <firstname>Tim</firstname><surname>Potter</surname>
- </author>
- <author>
- <firstname>Martin</firstname><surname>Pool</surname>
- </author>
-</chapterinfo>
-
-<title>Coding Suggestions</title>
-
-<para>
-So you want to add code to Samba ...
-</para>
-
-<para>
-One of the daunting tasks facing a programmer attempting to write code for
-Samba is understanding the various coding conventions used by those most
-active in the project. These conventions were mostly unwritten and helped
-improve either the portability, stability or consistency of the code. This
-document will attempt to document a few of the more important coding
-practices used at this time on the Samba project. The coding practices are
-expected to change slightly over time, and even to grow as more is learned
-about obscure portability considerations. Two existing documents
-<filename>samba/source/internals.doc</filename> and
-<filename>samba/source/architecture.doc</filename> provide
-additional information.
-</para>
-
-<para>
-The loosely related question of coding style is very personal and this
-document does not attempt to address that subject, except to say that I
-have observed that eight character tabs seem to be preferred in Samba
-source. If you are interested in the topic of coding style, two oft-quoted
-documents are:
-</para>
-
-<para>
-<ulink url="http://lxr.linux.no/source/Documentation/CodingStyle">http://lxr.linux.no/source/Documentation/CodingStyle</ulink>
-</para>
-
-<para>
-<ulink url="http://www.fsf.org/prep/standards_toc.html">http://www.fsf.org/prep/standards_toc.html</ulink>
-</para>
-
-<para>
-But note that coding style in Samba varies due to the many different
-programmers who have contributed.
-</para>
-
-<para>
-Following are some considerations you should use when adding new code to
-Samba. First and foremost remember that:
-</para>
-
-<para>
-Portability is a primary consideration in adding function, as is network
-compatibility with de facto, existing, real world CIFS/SMB implementations.
-There are lots of platforms that Samba builds on so use caution when adding
-a call to a library function that is not invoked in existing Samba code.
-Also note that there are many quite different SMB/CIFS clients that Samba
-tries to support, not all of which follow the SNIA CIFS Technical Reference
-(or the earlier Microsoft reference documents or the X/Open book on the SMB
-Standard) perfectly.
-</para>
-
-<para>
-Here are some other suggestions:
-</para>
-
-<orderedlist>
-
-<listitem><para>
- use d_printf instead of printf for display text
- reason: enable auto-substitution of translated language text
-</para></listitem>
-
-<listitem><para>
- use SAFE_FREE instead of free
- reason: reduce traps due to null pointers
-</para></listitem>
-
-<listitem><para>
- don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
- reason: not POSIX
-</para></listitem>
-
-<listitem><para>
- don't use strcpy and strlen (use safe_* equivalents)
- reason: to avoid traps due to buffer overruns
-</para></listitem>
-
-<listitem><para>
- don't use getopt_long, use popt functions instead
- reason: portability
-</para></listitem>
-
-<listitem><para>
- explicitly add const qualifiers on parm passing in functions where parm
- is input only (somewhat controversial but const can be #defined away)
-</para></listitem>
-
-<listitem><para>
- when passing a va_list as an arg, or assigning one to another
- please use the VA_COPY() macro
- reason: on some platforms, va_list is a struct that must be
- initialized in each function...can SEGV if you don't.
-</para></listitem>
-
-<listitem><para>
- discourage use of threads
- reason: portability (also see architecture.doc)
-</para></listitem>
-
-<listitem><para>
- don't explicitly include new header files in C files - new h files
- should be included by adding them once to includes.h
- reason: consistency
-</para></listitem>
-
-<listitem><para>
- don't explicitly extern functions (they are autogenerated by
- "make proto" into proto.h)
- reason: consistency
-</para></listitem>
-
-<listitem><para>
- use endian safe macros when unpacking SMBs (see byteorder.h and
- internals.doc)
- reason: not everyone uses Intel
-</para></listitem>
-
-<listitem><para>
- Note Unicode implications of charset handling (see internals.doc). See
- pull_* and push_* and convert_string functions.
- reason: Internationalization
-</para></listitem>
-
-<listitem><para>
- Don't assume English only
- reason: See above
-</para></listitem>
-
-<listitem><para>
- Try to avoid using in/out parameters (functions that return data which
- overwrites input parameters)
- reason: Can cause stability problems
-</para></listitem>
-
-<listitem><para>
- Ensure copyright notices are correct, don't append Tridge's name to code
- that he didn't write. If you did not write the code, make sure that it
- can coexist with the rest of the Samba GPLed code.
-</para></listitem>
-
-<listitem><para>
- Consider usage of DATA_BLOBs for length specified byte-data.
- reason: stability
-</para></listitem>
-
-<listitem><para>
- Take advantage of tdbs for database like function
- reason: consistency
-</para></listitem>
-
-<listitem><para>
- Don't access the SAM_ACCOUNT structure directly, they should be accessed
- via pdb_get...() and pdb_set...() functions.
- reason: stability, consistency
-</para></listitem>
-
-<listitem><para>
- Don't check a password directly against the passdb, always use the
- check_password() interface.
- reason: long term pluggability
-</para></listitem>
-
-<listitem><para>
- Try to use asprintf rather than pstrings and fstrings where possible
-</para></listitem>
-
-<listitem><para>
- Use normal C comments / * instead of C++ comments // like
- this. Although the C++ comment format is part of the C99
- standard, some older vendor C compilers do not accept it.
-</para></listitem>
-
-<listitem><para>
- Try to write documentation for API functions and structures
- explaining the point of the code, the way it should be used, and
- any special conditions or results. Mark these with a double-star
- comment start / ** so that they can be picked up by Doxygen, as in
- this file.
-</para></listitem>
-
-<listitem><para>
- Keep the scope narrow. This means making functions/variables
- static whenever possible. We don't want our namespace
- polluted. Each module should have a minimal number of externally
- visible functions or variables.
-</para></listitem>
-
-<listitem><para>
- Use function pointers to keep knowledge about particular pieces of
- code isolated in one place. We don't want a particular piece of
- functionality to be spread out across lots of places - that makes
- for fragile, hand to maintain code. Instead, design an interface
- and use tables containing function pointers to implement specific
- functionality. This is particularly important for command
- interpreters.
-</para></listitem>
-
-<listitem><para>
- Think carefully about what it will be like for someone else to add
- to and maintain your code. If it would be hard for someone else to
- maintain then do it another way.
-</para></listitem>
-
-</orderedlist>
-
-<para>
-The suggestions above are simply that, suggestions, but the information may
-help in reducing the routine rework done on new code. The preceding list
-is expected to change routinely as new support routines and macros are
-added.
-</para>
-</chapter>
diff --git a/docs-xml/Samba-Developers-Guide/Tracing.xml b/docs-xml/Samba-Developers-Guide/Tracing.xml
deleted file mode 100644
index 50ad2eeb37b..00000000000
--- a/docs-xml/Samba-Developers-Guide/Tracing.xml
+++ /dev/null
@@ -1,131 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<chapter id="tracing">
-<chapterinfo>
- <author>
- <firstname>Andrew</firstname><surname>Tridgell</surname>
- <affiliation>
- <orgname>Samba Team</orgname>
- </affiliation>
- </author>
-</chapterinfo>
-
-<title>Tracing samba system calls</title>
-
-<para>
-This file describes how to do a system call trace on Samba to work out
-what its doing wrong. This is not for the faint of heart, but if you
-are reading this then you are probably desperate.
-</para>
-
-<para>
-Actually its not as bad as the the above makes it sound, just don't
-expect the output to be very pretty :-)
-</para>
-
-<para>
-Ok, down to business. One of the big advantages of unix systems is
-that they nearly all come with a system trace utility that allows you
-to monitor all system calls that a program is making. This is
-extremely using for debugging and also helps when trying to work out
-why something is slower than you expect. You can use system tracing
-without any special compilation options.
-</para>
-
-<para>
-The system trace utility is called different things on different
-systems. On Linux systems its called strace. Under SunOS 4 its called
-trace. Under SVR4 style systems (including solaris) its called
-truss. Under many BSD systems its called ktrace.
-</para>
-
-<para>
-The first thing you should do is read the man page for your native
-system call tracer. In the discussion below I'll assume its called
-strace as strace is the only portable system tracer (its available for
-free for many unix types) and its also got some of the nicest
-features.
-</para>
-
-<para>
-Next, try using strace on some simple commands. For example, <command>strace
-ls</command> or <command>strace echo hello</command>.
-</para>
-
-<para>
-You'll notice that it produces a LOT of output. It is showing you the
-arguments to every system call that the program makes and the
-result. Very little happens in a program without a system call so you
-get lots of output. You'll also find that it produces a lot of
-"preamble" stuff showing the loading of shared libraries etc. Ignore
-this (unless its going wrong!)
-</para>
-
-<para>
-For example, the only line that really matters in the <command>strace echo
-hello</command> output is:
-</para>
-
-<para><programlisting>
-write(1, "hello\n", 6) = 6
-</programlisting></para>
-
-<para>all the rest is just setting up to run the program.</para>
-
-<para>
-Ok, now you're familiar with strace. To use it on Samba you need to
-strace the running smbd daemon. The way I tend to use it is to first
-login from my Windows PC to the Samba server, then use smbstatus to
-find which process ID that client is attached to, then as root I do
-<command>strace -p PID</command> to attach to that process. I normally redirect the
-stderr output from this command to a file for later perusal. For
-example, if I'm using a csh style shell:
-</para>
-
-<para><command>strace -f -p 3872 >& strace.out</command></para>
-
-<para>or with a sh style shell:</para>
-
-<para><command>strace -f -p 3872 > strace.out 2>&1</command></para>
-
-<para>
-Note the "-f" option. This is only available on some systems, and
-allows you to trace not just the current process, but any children it
-forks. This is great for finding printing problems caused by the
-"print command" being wrong.
-</para>
-
-<para>
-Once you are attached you then can do whatever it is on the client
-that is causing problems and you will capture all the system calls
-that smbd makes.
-</para>
-
-<para>
-So how do you interpret the results? Generally I search through the
-output for strings that I know will appear when the problem
-happens. For example, if I am having trouble with permissions on a file
-I would search for that files name in the strace output and look at
-the surrounding lines. Another trick is to match up file descriptor
-numbers and "follow" what happens to an open file until it is closed.
-</para>
-
-<para>
-Beyond this you will have to use your initiative. To give you an idea
-of what you are looking for here is a piece of strace output that
-shows that <filename>/dev/null</filename> is not world writeable, which
-causes printing to fail with Samba:
-</para>
-
-<para><programlisting>
-[pid 28268] open("/dev/null", O_RDWR) = -1 EACCES (Permission denied)
-[pid 28268] open("/dev/null", O_WRONLY) = -1 EACCES (Permission denied)
-</programlisting></para>
-
-<para>
-The process is trying to first open <filename>/dev/null</filename> read-write
-then read-only. Both fail. This means <filename>/dev/null</filename> has
-incorrect permissions.
-</para>
-
-</chapter>
diff --git a/docs-xml/Samba-Developers-Guide/architecture.xml b/docs-xml/Samba-Developers-Guide/architecture.xml
deleted file mode 100644
index f1ec70c99be..00000000000
--- a/docs-xml/Samba-Developers-Guide/architecture.xml
+++ /dev/null
@@ -1,186 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<chapter id="architecture">
-<chapterinfo>
- <author>
- <firstname>Dan</firstname><surname>Shearer</surname>
- </author>
- <pubdate> November 1997</pubdate>
-</chapterinfo>
-
-<title>Samba Architecture</title>
-
-<sect1>
-<title>Introduction</title>
-
-<para>
-This document gives a general overview of how Samba works
-internally. The Samba Team has tried to come up with a model which is
-the best possible compromise between elegance, portability, security
-and the constraints imposed by the very messy SMB and CIFS
-protocol.
-</para>
-
-<para>
-It also tries to answer some of the frequently asked questions such as:
-</para>
-
-<orderedlist>
-<listitem><para>
- Is Samba secure when running on Unix? The xyz platform?
- What about the root privileges issue?
-</para></listitem>
-
-<listitem><para>Pros and cons of multithreading in various parts of Samba</para></listitem>
-
-<listitem><para>Why not have a separate process for name resolution, WINS, and browsing?</para></listitem>
-
-</orderedlist>
-
-</sect1>
-
-<sect1>
-<title>Multithreading and Samba</title>
-
-<para>
-People sometimes tout threads as a uniformly good thing. They are very
-nice in their place but are quite inappropriate for smbd. nmbd is
-another matter, and multi-threading it would be very nice.
-</para>
-
-<para>
-The short version is that smbd is not multithreaded, and alternative
-servers that take this approach under Unix (such as Syntax, at the
-time of writing) suffer tremendous performance penalties and are less
-robust. nmbd is not threaded either, but this is because it is not
-possible to do it while keeping code consistent and portable across 35
-or more platforms. (This drawback also applies to threading smbd.)
-</para>
-
-<para>
-The longer versions is that there are very good reasons for not making
-smbd multi-threaded. Multi-threading would actually make Samba much
-slower, less scalable, less portable and much less robust. The fact
-that we use a separate process for each connection is one of Samba's
-biggest advantages.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Threading smbd</title>
-
-<para>
-A few problems that would arise from a threaded smbd are:
-</para>
-
-<orderedlist>
-<listitem><para>
- It's not only to create threads instead of processes, but you
- must care about all variables if they have to be thread specific
- (currently they would be global).
-</para></listitem>
-
-<listitem><para>
- if one thread dies (eg. a seg fault) then all threads die. We can
- immediately throw robustness out the window.
-</para></listitem>
-
-<listitem><para>
- many of the system calls we make are blocking. Non-blocking
- equivalents of many calls are either not available or are awkward (and
- slow) to use. So while we block in one thread all clients are
- waiting. Imagine if one share is a slow NFS filesystem and the others
- are fast, we will end up slowing all clients to the speed of NFS.
-</para></listitem>
-
-<listitem><para>
- you can't run as a different uid in different threads. This means
- we would have to switch uid/gid on _every_ SMB packet. It would be
- horrendously slow.
-</para></listitem>
-
-<listitem><para>
- the per process file descriptor limit would mean that we could only
- support a limited number of clients.
-</para></listitem>
-
-<listitem><para>
- we couldn't use the system locking calls as the locking context of
- fcntl() is a process, not a thread.
-</para></listitem>
-
--
Samba Shared Repository
More information about the samba-cvs
mailing list